PHPackages userapp/userapp - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. userapp/userapp ActiveLibrary[Authentication & Authorization](/categories/authentication) userapp/userapp =============== PHP client library for UserApp. 1.2.2(11y ago)61.2k21MITPHPPHP >=5.3.2 Since Jun 19Pushed 11y ago1 watchersCompare [ Source](https://github.com/userapp-io/userapp-php)[ Packagist](https://packagist.org/packages/userapp/userapp)[ Docs](http://github.com/userapp-io/userapp-php)[ RSS](/packages/userapp-userapp/feed)WikiDiscussions master Synced 2mo ago READMEChangelogDependenciesVersions (9)Used By (1) PHP library for UserApp ======================= [](#php-library-for-userapp) [![Build Status](https://camo.githubusercontent.com/246763602d37a031e1f4f9c2a204f28c5a7c47c720c0015e717db3069401ac7f/68747470733a2f2f7472617669732d63692e6f72672f757365726170702d696f2f757365726170702d7068702e706e67)](https://travis-ci.org/userapp-io/userapp-php)[![Code Quality](https://camo.githubusercontent.com/174167eecc5256df440a14c33e23bcc417f7b394758c71fae0f7fed5ae126c0a/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f757365726170702d696f2f757365726170702d7068702f6261646765732f7175616c6974792d73636f72652e706e673f733d34373331623865333365346635383636663238613162396361666232336238336433396439373932)](https://scrutinizer-ci.com/g/userapp-io/userapp-php/) Getting started --------------- [](#getting-started) ### Finding your App Id and Token [](#finding-your-app-id-and-token) If you don't have a UserApp account, you need to [create one](https://app.userapp.io/#/sign-up/). - **App Id**: The App Id identifies your app. After you have logged in, you should see your `App Id` instantly. If you're having trouble finding it, [follow this guide](https://help.userapp.io/customer/portal/articles/1322336-how-do-i-find-my-app-id-). - **Token**: A token authenticates a user on your app. If you want to create a token for your logged in user, [follow this guide](https://help.userapp.io/customer/portal/articles/1364103-how-do-i-create-an-api-token-). If you want to authenticate using a username/password, you can acquire your token by calling `$api->user->login(...);` ### Loading the library [](#loading-the-library) UserApp relies on the autoloading features of PHP to load its files when needed. The autoloading complies with the PSR-0 standard which makes it compatible with most of the major frameworks and libraries. Autoloading in your application is handled automatically when managing the dependencies with [Composer](https://packagist.org/packages/userapp/userapp). #### Using Composer? Add this to your `composer.json` [](#using-composer-add-this-to-your-composerjson) ``` { "require": { "userapp/userapp": "~1.1.0" } } ``` #### Not using Composer? Use the library's own autoloader [](#not-using-composer-use-the-librarys-own-autoloader) ``` require 'autoload.php'; ``` ### Creating your first client [](#creating-your-first-client) ``` $api = new \UserApp\API("YOUR APP ID"); ``` #### Additional ways of creating a client [](#additional-ways-of-creating-a-client) If you want to create a client with additional options the easiest way is to pass an array with the options as shown below. ``` $api = new \UserApp\API(array( "debug" => true, "throw_errors" => false )); ``` If you pass a string value into the constructor the first argument will be treated as the `App Id`, the second as the `Token`. If you pass an *array* then it will always be treated as additional options. I.e. some valid constructs are: ``` $api = new \UserApp\API("MY APP ID"); ``` ``` $api = new \UserApp\API("MY APP ID", array( "option" => "some value" )); ``` ``` $api = new \UserApp\API("MY APP ID", "MY TOKEN", array( "option" => "some value" )); ``` Calling services and methods ---------------------------- [](#calling-services-and-methods) This client has no hard-coded API definitions built into it. It merly acts as a proxy which means that you'll never have to update the client once new API methods are released. If you want to call a service/method all you have to do is look at the [API documentation](https://app.userapp.io/#/docs/) and follow the convention below: ``` $result = $api->[service]->[method](array([argument] => [value])); ``` #### Some examples [](#some-examples) The API [`user.login`](https://app.userapp.io/#/docs/user/#login) and its arguments `login` and `password` translates to: ``` $login_result = $api->user->login(array( "login" => "test", "password" => "test" )); ``` The API [`user.invoice.search`](https://app.userapp.io/#/docs/invoice/#search) and its argument `user_id` translates to: ``` $invoices = $api->user->invoice->search(array( "user_id" => "test123" )); ``` The API [`property.save`](https://app.userapp.io/#/docs/property/#save) and its arguments `name`, `type` and `default_value` translates to: ``` $property = $api->property->save(array( "name" => "my new property", "type" => "boolean", "default_value" => true )); ``` The API [`user.logout`](https://app.userapp.io/#/docs/user/#logout) without any arguments translates to: ``` $api->user->logout(); ``` Configuration ------------- [](#configuration) Options determine the configuration of a client. If no options are passed to a client, the options will automatically be inherited from the client global options (`\UserApp\ClientOptions->getGlobal()`). ### Available options [](#available-options) - **Version** (`version`): Version of the API to call against. Default `1`. - **App Id** (`app_id`): App to authenticate against. Default `null`. - **Token** (`token`): Token to authenticate with. Default `null`. - **Debug mode** (`debug`): Log steps performed when sending/receiving data from UserApp. Default: `false`. - **Secure mode** (`secure`): Call the API using HTTPS. Default: `true`. - **Base address** (`base_address`): The address to call against. Default: `api.userapp.io`. - **Throw errors** (`throw_errors`): Whether or not to throw an exception when response is an error. I.e. result `{"error_code":"SOME_ERROR","message":"Some message"}` results in an exception of type `\UserApp\Exceptions\ServiceException`. ### Setting options [](#setting-options) Options can either be set in global or local scope. Global is the scope in which all clients inherit their default options from. #### Global scope [](#global-scope) Global options can be set using ``` \UserApp\API::setGlobalOptions(array( "app_id" => "MY APP ID", "token" => "MY TOKEN" )). ``` ### Local scope [](#local-scope) The easiest way to set a local scoped option is to do it in the constructor when creating a new client. ``` $api = new \UserApp\API(array( "debug" => true, "throw_errors" => false )); ``` If you want to set an option after the client has been created you can do it as shown below. ``` $api->setOption("debug", true); ``` Setting multiple options is done almost the same way. ``` $api->setOptions(array( "debug" => true, "throw_errors" => false )); ``` Example code ------------ [](#example-code) A more detailed set of examples can be found in /examples. ### Example code (sign up a new user) [](#example-code-sign-up-a-new-user) ``` $api = new \UserApp\API("YOUR APP-ID"); $api->user->save(array( "login" => "johndoe81", "password" => "iwasfirst!111" )); ``` ### Example code (logging in and updating a user) [](#example-code-logging-in-and-updating-a-user) ``` $api = new \UserApp\API("YOUR APP-ID"); $api->user->login(array( "login" => "johndoe81", "password" => "iwasfirst!111" )); $api->user->save(array( "user_id" => "self", "first_name" => "John", "last_name" => "Doe" )); $api->user->logout(); ``` ### Example code (finding a specific user) [](#example-code-finding-a-specific-user) ``` $api = new \UserApp\API("YOUR APP-ID", "YOUR TOKEN"); $search_result = $api->user->search(array( "filters" => array( "query" => "*bob*" ), "sort" => array( "created_at" => "desc" ) )); print_r($search_result->items); ``` Versioning ---------- [](#versioning) If you want to configure the client to call a specific API version you can do it by either setting the `version` option, or by calling the client using the convention `$api->v[version number]`. If no version is set it will automatically default to `1`. ### Examples [](#examples) Since no version has been specified, this call will be made against version `1` (default). ``` $api->user->login(array("login" => "test", "password" => "test")); ``` Since the version has been explicitly specified using options, the call will be made against version `2`. ``` $api = new \UserApp\API(array("version" => 2)); $api->user->login(array("login" => "test", "password" => "test")); ``` Since the version has been explicitly specified, the call will be made against version `3`. ``` $api->v3->user->login(array("login" => "test", "password" => "test")); ``` Events ------ [](#events) This library emits the following events: - **success** Emitted when a call succeeds. - **error** Emitted when a call results in an error. - **unauthorized** Emitted when a call results in an authentication error. Emitted before emitting the *error* event. ### Listening to events [](#listening-to-events) ``` $api->on('success', function($sender, $call_context, $result){ echo(sprintf("Call to %s.%s resulted in %s", $call_context->service, $call_context->method, json_encode($result))); }); ``` Error handling -------------- [](#error-handling) ### Debugging [](#debugging) Sometimes to debug an API error it's important to see what is being sent/received from the calls that one make to understand the underlying reason. If you're interested in seeing these logs, you can set the client option `debug` to `true`, then print the logs after you've made your API call (as shown below). ``` $api = new \UserApp\API(array("debug" => true)); $api->user->login(array("login" => "test", "password" => "test")); print_r($api->getLogger()->getLogs()); ``` ### Catching errors [](#catching-errors) When the option `throw_errors` is set to `true` (default) the client will automatically throw a `\UserApp\Exceptions\ServiceException` exception when a call results in an error. I.e. ``` try{ $api->user->save(array("user_id" => "invalid user id")); }catch(\UserApp\Exceptions\ServiceException $exception){ switch($exception->getErrorCode()){ // Handle specific error case "INVALID_ARGUMENT_USER_ID": throw new Exception("User does not exist"); default: throw $exception; } } ``` Setting `throw_errors` to `false` is more of a way to tell the client to be silent. This will not throw any service specific exceptions. Though, it might throw a `\UserApp\Exceptions\UserAppException`. ``` $result = $api->user->save(array("user_id" => "invalid user id")); if(is_object($result) && isset($result->error_code)){ if($result->error_code == "INVALID_ARGUMENT_USER_ID"){ // Handle specific error } } ``` ### Intercepting errors with events [](#intercepting-errors-with-events) #### All errors [](#all-errors) ``` $api->on('error', function($sender, $call_context, $error){ echo(sprintf("Call to %s.%s resulted in error %s (%s)", $call_context->service, $call_context->method, $error->message, $error->error_code))); }); ``` #### Only unauthorized events [](#only-unauthorized-events) ``` $api->on('unauthorized', function($sender, $call_context, $error){ header("Location: /login.php"); die(); }); ``` Solving issues -------------- [](#solving-issues) ### See what is being sent to/from UserApp [](#see-what-is-being-sent-tofrom-userapp) 1. Set the client option `debug` to `true` (see section *options* for more details on setting client options). If no logger is set, this automatically adds a MemoryLogger to your API client. The logger is retrievable using `$api->getLogger()`. 2. Like above, set the option `throw_errors` to `false`. This disables any error exceptions (`\UserApp\Exceptions\ServiceException`) being thrown. 3. Make the API calls that you want to debug. E.g. `$user->user->login(array("login" => "test"));` 4. Print the logs! `print_r($api->getLogger()->getLogs());` 5. Stuck? Send the output to and we'll help you out. ### Common errors [](#common-errors) ##### Exception: This transport requires that the cURL PHP extension is installed. [](#exception-this-transport-requires-that-the-curl-php-extension-is-installed) You are missing the cURL extension. Follow these instructions to install it: (Ubuntu) ##### PHP Fatal error: Call to undefined function json\_encode(). [](#php-fatal-error--call-to-undefined-function-json_encode) Try executing: `# sudo apt-get install php5-json` (Ubuntu). Special cases ------------- [](#special-cases) Even though this client works as a proxy and there are no hard-coded API definitions built into it, there are still a few tweaks that are API specific. #### Calling API `user.login` will automatically set the client token [](#calling-api-userlogin-will-automatically-set-the-client-token) In other words: ``` $login_result = $api->user->login(array("login" => "test", "password" => "test")); ``` Is exactly the same as: ``` $login_result = $api->user->login(array("login" => "test", "password" => "test")); $api->setOption("token", $login_result->token); ``` #### Calling API `user.logout` will automatically remove the client token [](#calling-api-userlogout-will-automatically-remove-the-client-token) In other words: ``` $api->user->logout(); ``` Is exactly the same as: ``` $api->user->logout(); $api->setOption("token", null); ``` Dependencies ------------ [](#dependencies) - PHP >= 5.3.2 - [cURL](http://php.net/manual/en/book.curl.php) License ------- [](#license) MIT - For more details, see LICENSE. ### Health Score 32 — LowBetter than 72% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity21 Limited adoption so far Community14 Small or concentrated contributor base Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 53.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~6 days Total 8 Last Release 4300d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2841885?v=4)[userapp](/maintainers/userapp)[@userapp](https://github.com/userapp) --- Top Contributors [![UserAppIO](https://avatars.githubusercontent.com/u/5843599?v=4)](https://github.com/UserAppIO "UserAppIO (36 commits)")[![typerandom](https://avatars.githubusercontent.com/u/1331778?v=4)](https://github.com/typerandom "typerandom (30 commits)")[![pborreli](https://avatars.githubusercontent.com/u/77759?v=4)](https://github.com/pborreli "pborreli (1 commits)") --- Tags User managementuser authentication ### Embed Badge ![Health badge](/badges/userapp-userapp/health.svg) ``` [![Health](https://phpackages.com/badges/userapp-userapp/health.svg)](https://phpackages.com/packages/userapp-userapp) ``` ### Alternatives [friendsofsymfony/user-bundle Symfony FOSUserBundle 3.2k35.4M311](/packages/friendsofsymfony-user-bundle)[2amigos/yii2-usuario Highly customizable and extensible user management, authentication, and authorization Yii2 extension 298275.5k14](/packages/2amigos-yii2-usuario)[nucleos/user-bundle Lightweight user management for symfony 61380.7k5](/packages/nucleos-user-bundle)[tomatophp/filament-users Manage your users with a highly customizable user resource for FilamentPHP with integration of filament-shield and filament-impersonate 90102.0k7](/packages/tomatophp-filament-users)[nucleos/profile-bundle Registration and profile management for symfony 12218.5k1](/packages/nucleos-profile-bundle)[saeven/zf3-circlical-user Complete user entity, rights, and access module for Laminas 3718.7k](/packages/saeven-zf3-circlical-user) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)