Skip to content

Latest commit

 

History

History
executable file
·
457 lines (375 loc) · 16.4 KB

BasicUsage.md

File metadata and controls

executable file
·
457 lines (375 loc) · 16.4 KB

Configuration

This guide shows you have to set the right configuration. The basic config array looks like this, but with this configuration you only can access data that needs no right to access.

 'default' => [
       //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword'
        ]

The recommended configuration is when you have an default and an admin configuration, so you can fetch all data from the api. The admin account doesn't have to be an admin account it is enough when you give him full reading permission.

 'default' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword'
    ],
  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ]

if you want to change the path scheme, for example if your domain is not webuntis.com you can use this config. The keywords {school} and {server} will be replaced with the server name and school, you can also leave them out if you don't have such a thing. In summary you can build your own domain/url.

 'default' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword',
        //this is the default path scheme
        'path_scheme' => 'https://{server}.webuntis.com/WebUntis/jsonrpc.do?school={school}'
    ],
  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword',
        //this is the default path scheme
        'path_scheme' => 'https://{server}.webuntis.com/WebUntis/jsonrpc.do?school={school}'
    ]

if you want to turn off caching (which is not recommended) take this configuration:

 'default' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword'
    ],
  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ],
    'disable_cache' => true

if you don't want the default memcached(port=11211, host=localhost) server use:

 'default' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword'
    ],
  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ],
    'cache' => [
        'type' => 'memcached',
        'host' => 'yourhost',
        'port' => 'yourport
    ]

there is also a filebased caching server

 'default' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword'
    ],
  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ],
    'cache' => [
        'type' => 'filesystem',
        'path' => 'your/path/to/the/cache'
    ]

if you want to execute all models with the admin instance

  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ],
    'only_admin' => true

if you have changed the vendor dir in the composer.json config you can add this parameter

  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ],
    'vendor_dir' => 'lib'

if you want to use another SecurityManager you can use this config. With an custom Security Manager you can return your own Client. You just have to implement the Webuntis\Security\Interfaces\SecurityManagerInterface and create the method you need (getClient, getCurrentUserId, getCurrentUserType) and return the right things according to the method. With the method getClient() you can return your own client which is then used by the ExecutionHandler to execute http request to apis, the client class must have an call method. F.e. you could return your own Client thats accesses an complietly differently api (not webuntis) and use this library in an complettly other way.

  'admin' => [
        //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ],
    'security_manager' => 'Your\Namespace\Manager'

Often you have to request api endpoint with normal users for example Periods, but there is the Problem that the childs that you have in the Periods Model like Teachers and Students need admin access, the problem that arises from this is that you get your access denied. With the option ignore_children you can disable the rendering of the children, so you don't need to access there end points too. just add the option to the instance you want it to work on.

use Webuntis\Configuration\WebuntisConfiguration;

$config = new WebuntisConfiguration([ 
'default' => [
       //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword',
        'ignore_children' => true
    ],
    'admin' => [
       //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ]
 ]);

At the moment there is a problem with webuntis that all access right have changed, so your account could be found in the Students Repository but has not the UserType 5. There is now an option per instance to define a default User Repository, where the User will be searched for when you login. When you don't define this property and you have a UserType other then 2 or 5 you will get returned the Webuntis\Models\Account class, which has minimal definition (userId, userType).

use Webuntis\Configuration\WebuntisConfiguration;

$config = new WebuntisConfiguration([ 
'default' => [
       //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword',

        // when calling ->getCurrentUser() the user will be 
        // searched in the Students repository even if the returned UserType is a Teacher or other
        // $query->get('Students')->findBy(['id' => $this->currentUserId])[0];
        'user_type' => 'Students'
    ],
    'admin' => [
       //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ]
 ]);

To apply the configuration you have to simply create a new WebuntisConfiguration object.

use Webuntis\Configuration\WebuntisConfiguration;

$config = new WebuntisConfiguration([ 
'default' => [
       //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'yourusername',
        'password' => 'yourpassword'
    ],
'admin' => [
       //f.e. thalia, cissa etc.
        'server' => 'yourserver',
        'school' => 'yourschool',
        'username' => 'youradminusername',
        'password' => 'youradminpassword'
    ]
 ]);

Querys

Now to the important part, the data fetching.

You just have to create a new Query object.

use Webuntis\Query\Query;

$query = new Query();

if you call

$query->get('Students');

you get an Repository object which has already defined functions that allow you to fetch the data from the api. the get Parameter is always the model which gets the data from a certain api method.

Repositories

every Repository has custom method the default Repository has these 2 methods:

$query->get('Students')->findAll();

if you call this method you get all Students in this case

$query->get('Students')->findBy(['firstName' => 'seppi']);

this method return all the students with the first name 'seppi'

you also can search recursively like this:

$query->get('Period')->findBy(['teachers:firstName' => 'seppi']);

this will return all the Period Models where the teachers have the first name 'seppi'

you also can search if a certain string exists in a firstName like this:

$query->get('Period')->findBy(['teachers:firstName' => '%epp%']);

you can compare dates also:

$query->get('Period')->findBy(['startDate' => '<Y-m-d']);

The < is how you want to compare the date < for <= and > for >=:

possible formats:

  • Y-m-d H:i
  • Y-m-d

You can sort the given output.

$query->get('Exams')->findAll(['startDate' => 'ASC|DESC']);

//you can sort by properties that are in objects that the main objects contains, but that is restricted to one level
$query->get('Exams')->findAll(['teachers:firstName' => 'ASC|DESC']);

This will either order the model descending (DESC) or ascending (ASC).

You can now give a limit to the query.

$query->get('Exams')->findAll(['startDate' => 'ASC|DESC'], 5);

Custom Repositories

There are six custom Repositories in the core already and they are the

  • PeriodRepository only has some additional parameters to the standard methods.
$query->get('Period')->findAll(sort, limit, options);
//options is a array and can contain these values for filtering
// - options a parameter object encapsulating the following fields:
//      - element id object encapsulating the following fields:
//          - id element id, either the internal id, name, or external key of an element (see „keyType“), mandatory
//           - type element type, mandatory 1 = klasse, 2 = teacher, 3 = subject, 4 = room, 5 = student
//      - keyType „id“, „name“, or„externalkey“, optional (default: „id“)
//      - startDate number, format: YYYYMMDD, optional (default: current date)
//      - endDate number, format: YYYYMMDD, optional (default: current date)
//      - onlyBaseTimetable boolean, returns only the base timetable (without bookings etc.) (default:false)
//      - showBooking boolean, returns the period's booking info if available (default: false)
//      - showInfo boolean, returns the period information if available (default: false)
//      - showSubstText boolean, returns the Untis substitution text if available (default: false)
//      - showLsText boolean, returns the text of the period's lesson (default: false)
//      - showLsNumber boolean, returns the number of the period's lesson (default: false)
//      - showStudentgroup boolean, returns the name(s) of the studentgroup(s) (default: false)
//      - klasseFields array, optional, values: „id“, „name“, „longname“, „externalkey“
//      - roomFields array, optional, values: „id“, „name“, „longname“, „externalkey“
//      - subjectFields array, optional, values: „id“, „name“, „longname“, „externalkey“
//      - teacherFields array, optional, values: „id“, „name“, „longname“, „externalkey“
  • Exams has some different logic in the findAll() method.
  • ClassHasTeachers has some different logic in the findAll() method.
  • SubstitutionsRepository has some additional MANDATORY parameters to the standard methods.
//department is not mandatory
$query->get('Substitution')->findAll(department, startDate, endDate);
  • UserRepository with these additional functions (This Repository can only execute these functions):
$query->get('User')->getCurrentUser();
$query->get('User')->getCurrentUserType();
  • SchoolyearsRepository has one additional method, which allows you to fetch the current schoolyear:
$query->get('Schoolyears')->getCurrentSchoolyear()
  • ClassRegEventsRespository needs some additional madatory parameters
$query->get('ClassRegEvents')->findAll([], null, startDate, endDate, element);
// element is a option that the api offers to filter the class reg events it should loog like this
// - element
//     - id id of the element, e.g. „Tobermory“
//     - type type of the element, 1 = klasse, 5 = student
//     - keyType „id“, „name“, or „externalkey“, (default: „id“)

  • LastImportTimeRepository just has a different parse method, because the returned data from the api is not an array.

  • StatusDataRepository again just a different parse method.

  • AbsencesRespoitory allows you to fetch absences from a certain date

$query->get('Absences')->findAll([], null, startDate, endDate, lazy = true|false);
// the lazy operator works like this

// loads all the data and works just as fine
$absence = $query->get('Absences')->findAll([], null, startDate, endDate, lazy = false)[0];
$absence->getTeachers()[0]->getName();

// it loads all the children etc for the absences model
$absences = $query->get('Absences')->findAll([], null, startDate, endDate, lazy = false);
\Webuntis\Serializer\Serializer::serialize($absences)[12]['teachers'][2]->getName()

// now with lazy enabled this happens
$absence = $query->get('Absences')->findAll([], null, startDate, endDate, lazy = true)[0];

// Error: undefined method
$absence->getTeachers()[0]->getName();
// and also all other object only have the base data
// but if you load them:
// everything works as before, but you had to process a lot less data at once
// keep in mind, with this command you have to load one model at a time
$absence->load()->getTeachers()[0]->getName();

Model Usage

These are all the models that exists in the core build:

  • Classes - api method: getKlassen
  • Departments - api method: getDepartments
  • Holidays - api method: getHolidays
  • Period - api method: getTimetable
  • Rooms - api method: getRooms
  • Students - api method: getStudents
  • Subjects - api method: getSubjects
  • Teachers - api method: getTeachers
  • ClassHasTeachers - show all teachers according to that class, be careful it is extremely slow
  • Exams - api method: getExams
  • Substitutions - api method: getSubstitutions
  • Schoolyears - api method: getSchoolyears/getCurrentSchoolyear
  • ExamTypes - api method: getExamTypes
  • TimegridUnits - api method: getTimegridUnits
  • ClassRegEvents - api method: getClassregEvents
  • StatusData - api method: getStatusData
  • LastImportTime - api method: getLatestImportTime
  • Absences - api method: getTimetableWithAbsences
  • RemarkCategories - api method: getClassregCategories
  • RemarkCategoryGroups - api method: getClassregCategoryGroups

Serializer

all the Repository method return an array of Model objects. If you want to serialize the Object you only need to call the serialize() method on an object, this method then return an array:

$user = $query->get('User')->getCurrentUser(); // returns an object
$user = $user->serialize(); // turn the object into an array

If you want an other format(supported: json, xml, yml) you can to write this:

$user = $query->get('User')->getCurrentUser(); // returns an object
$user = $user->serialize('json|xml|yml'); // turn the object into one of these formats

If you have an array of objects you can serialize the array including the models that are in there, you have to call the Serializer class:

$students = $query->get('Students')->findAll(); // returns an object array
$students =  \Webuntis\Serializer\Serializer::serialize($students, 'json|xml|yml') // turn the object array into an array,
                                                                                   // if the second parameter is empty it will return an php array

original API data

If you want to get the originally received API data from the json rpc end point, call the

$students = $query->get('Students')->findAll()[0]->getAttributes(); // returns the original received array