Matrix-PHP
A simple library that allows to interact with a Matrix instance through the API.
License
Matrix-PHP is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version. Please see LICENSE file for the terms of GNU General Public License.
Dependencies
- curl
Installation
Manually (on Ubuntu)
$ sudo apt install php-curl
$ git clone https://github.com/artyom-poptsov/matrix-php.git
By Composer
Create composer.json in your project directory (or add dependencies to it):
{
"require": {
"artyom-poptsov/matrix-php": "dev-master"
},
"repositories": [
{
"type": "git",
"url": "https://github.com/artyom-poptsov/matrix-php"
}
]
}
Then execute:
$ composer install
Syncing with the upstream
$ composer update
Testing
$ composer run-script test
Generating API documentation
$ composer run-script doc
The documentation will be stored in doc directory.
Examples
Account creation
require_once('vendor/artyom-poptsov/matrix-php/matrix/Matrix.php');
use \matrix\Matrix;
$m = new Matrix('https://example.org:8448', 'secret-token');
// 'true' means that the created user will be granted admin rights.
try {
$m->request_registration('alice', 'passw0rd', true);
} catch (\matrix\Matrix_exception $e) {
if ($e->get_errcode() == 'M_USER_IN_USE') {
// Handle specific error.
}
// Do something else.
}
Login to the server
require_once('vendor/artyom-poptsov/matrix-php/matrix/Matrix.php');
use \matrix\Matrix;
$m = new Matrix('https://example.org:8448', 'secret-token');
$auth_methods = $m->get_available_login_methods();
// Only 'm.login.password' currently supported.
$session = $m->login('m.login.password', 'alice, 'passw0rd');
Please note that you should explicitly call logout method in order to finish
the session:
$session->logout();
Calling to the logout method invalidates the session.
Change your password, if you wish
$result = $session->change_password('passw0rd', 'passw1rd');
Create a room (using existing session)
$room = false;
try {
$room = $session->create_room("test");
} catch (Matrix_exception $e) {
if ($e->get_errcode() == "M_ROOM_IN_USE") {
// Handle specific error.
}
// Do something else.
}
Send a message to a room
$session = $m->login('m.login.password', 'alice, 'passw0rd');
$room = new Room('#test:example.org:8448, '!room-id:example.org:8448');
$event_id = $session->send_message($room, 'm.text', "hello");
Get admin rights
require_once('vendor/artyom-poptsov/matrix-php/matrix/Matrix.php');
use \matrix\Matrix;
$m = new Matrix('https://example.org:8448', 'secret-token');
$session = $m->login('m.login.password', 'alice, 'passw0rd');
// This method call may fail if 'alice' has insufficient rights
// ("This incident will be reported", you know):
$admin_session = $session->sudo();
Do your admin stuff
// 'make_fqn' method produces a Fully Qualified Name for the current Matrix server.
// For example: '@alice:example.org':
$fqn = $matrix->make_fqn('alice');
// 'false' here means that the user for whom the password was reset should NOT be
// logged out from all their devices (this is 'true' by default):
$admin_session->reset_password($fqn, 'new_password', false);
Deactivate an account
$fqn = $matrix->make_fqn('alice');
$admin_session->deactivate_account($fqn);