Magister 6 API Documentation Release 2.0 magister-api September 22, 2018
Contents 1 User Guide 3 1.1 Installation................................................ 3 1.1.1 Server Requirements...................................... 3 1.1.2 Installing the Magister 6 API.................................. 3 1.1.3 Configuration.......................................... 4 1.2 Configuration............................................... 4 1.2.1 Introduction........................................... 4 1.2.2 Environment Configuration................................... 4 1.3 Surrogates................................................ 5 1.3.1 Introduction........................................... 5 1.3.2 Surrogate Class Reference................................... 5 1.4 Authentication.............................................. 6 1.5 Models.................................................. 6 1.5.1 Grade.............................................. 6 i
ii
Magister 6 API Documentation, Release 2.0 Welcome to the documentation for our public Magister 6 API. This project aims to provide an easy-to-use and elegant bridge between your website and Magister 6. Please note that we are not affiliated with SchoolMaster s Magister in any way. // Set the encryption key. putenv("magister_encryption_key=$key"); // Instantiate the Magister object. new Magister\Magister($school, $username, $password); // Display today's appointments. foreach (Magister\Models\Appointment::today() as $appointment) { // Display the description of the appointment. echo $appointment->omschrijving; } Contents 1
Magister 6 API Documentation, Release 2.0 2 Contents
CHAPTER 1 User Guide Installation Server Requirements The Magister 6 API has a few system requirements. You will need to make sure your server meets the following requirements: PHP >= 5.4.0 curl PHP Extension Mcrypt PHP Extension OpenSSL PHP Extension Installing the Magister 6 API The Magister 6 API utilizes Composer to manage its dependencies. So, before using it, make sure you have Composer installed on your machine. You can add the Magister 6 API as a dependency using the Composer CLI: php composer.phar require stanvk/magister:~2.0 Alternatively, you can specify the Magister 6 API as a dependency in your project s existing composer.json file: { } "require": { "stanvk/magister": "~2.0" } Make sure you run the php composer.phar install command after modifying your composer.json file in order to update your vendor directory. After installing, you need to require Composer s autoloader: require 'vendor/autoload.php'; You can find out more on how to install Composer, configure autoloading, and other best-practices for defining dependencies at getcomposer.org. 3
Magister 6 API Documentation, Release 2.0 Configuration Configuration Files All of the configuration files for the Magister 6 API are stored in the config directory. Feel free to look through the files and get familiar with the options available to you. Encryption Key The next thing you should do after installing the Magister 6 API is set your encryption key to a random string. Typically, this string should be 32 characters long. The key can be set in your PHP environment. The Magister 6 API ships with a function that generates a secure encryption key. You might generate a 32 characers long secure encryption key like this: str_random(32); For more information on how to set the encryption key in your environment, visit the configuration section of the documentation. If the encryption key is not set, your user sessions and other encrypted data will not be secure! Configuration Introduction All of the configuration files for the Magister 6 API are stored in the config directory. Feel free to look through the files and get familiar with the options available to you. Environment Configuration The Magister 6 API stores the configuration in the environment. It is often helpful to have different configuration values based on the environment the application is running in. There are two ways of modifying the Magister 6 API s configuration, one utilizing a third party package and one utilizing native PHP. Both of these ways serve the same purpose, although in a different way. Using the DotEnv PHP library The DotEnv PHP library by Vance Lucas uses a.env file to load environment variables to the PHP environment. You will need to add this package to your Composer requirements. Once this is done, simply create a.env file in your root directory and define your configuration options in there. See the.env.example file provided by the Magister 6 API for a sample configuration. You need to instantiate the Dotenv class before creating a Magister instance: (new Dotenv\Dotenv( DIR ))->load(); $magister = new Magister\Magister(...); For more information on how to use phpdotenv, visit their GitHub page. 4 Chapter 1. User Guide
Magister 6 API Documentation, Release 2.0 Using native PHP Although the DotEnv PHP library is our preferred method, the same is possible without using any third party packages while sticking to native PHP functions. We need to use the following function to create an environment variable: putenv("foo=bar"); This will set the environment variable FOO to the value BAR. This does the exact same as the phpdotenv package, although instead of in a.env file, the environment variables are defined directly in your code. Likewise, these need to be defined before you create the Magister object. You can imagine this becoming a mess when you need to define multiple environment variables like this. Retrieving Environment Configuration All of the configuration variables defined will be loaded into the $_ENV PHP super-global when your application receives a request. The Magister 6 API uses an env helper to retrieve the values from these variables in the configuration files. 'key' => env('magister_encryption_key', null), The second value passed to the env function is the default value. This value will be used if no environment variable exists for the given key. By default all Magister configuration options are prefixed by MAGISTER_. Surrogates Introduction Surrogates provide a static interface to classes that are available in the application s service container. The Magister 6 API ships with many surrogates which provide access to almost all of the Magister 6 API s features. The Magister 6 API s surrogates serve as static proxies to underlying classes in the service container, providing the benefit of a terse, expressive syntax while maintaining more testability and flexibility than traditional static methods. All of the Magister 6 API s surrogates are defined in the Magister\Services\Support\Surrogates namespace. So, we can easily access a surrogate like so: use Magister\Services\Support\Surrogates\Config; echo Config::get('app.key'); Throughout the Magister 6 API s documentation, many of the examples will use surrogates to demonstrate various features of the API. Surrogate Class Reference Below you will find every surrogate and its underlying class. This is a useful tool for quickly digging into the API documentation for a given surrogate root. The service container binding key is also included where applicable. 1.3. Surrogates 5
Magister 6 API Documentation, Release 2.0 Surrogate Class Service Container Binding App Magister\Magister app Auth Magister\Services\Auth\AuthManager auth Config Magister\Services\Config\Repository config Cookie Magister\Services\Cookie\CookieJar cookie Crypt Magister\Services\Encryption\Encrypter encrypter Event Magister\Services\Events\Dispatcher events File Magister\Services\Filesystem\Filesystem files Http GuzzleHttp\Client http Authentication WIP Models A model is the interface between the API and your code. Each model has a set of default methods and optional model specific methods. Grade Clearly, this model can be used to retrieve information about grades. After creating a instance of the Magister class, a model can be used by first including the corresponding namespace: use Magister\Models\Grade\Grade; Retrieving all grades Since the Magister API utilizes surrogates, each model can be treated as a static class. For example, if one whishes to retrieve all grades, one can simply do: $grades = Grade::all(); Retrieving the first grade The first grade can be retrieved by doing: $grade = Grade::first(); Request parameters At some models, the user can specify parameters. This can be done with the where() function. For example: $grades = Grade::where('actievePerioden', 'false')->get(); 6 Chapter 1. User Guide