PHPackages twigger/unioncloud - 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. [API Development](/categories/api) 4. / 5. twigger/unioncloud ActiveLibrary[API Development](/categories/api) twigger/unioncloud ================== An API Wrapper for the NUS UnionCloud platform v1.0.11(3y ago)1807[1 PRs](https://github.com/bristol-su/nus-unioncloud-api-wrapper/pulls)1GPL-3.0-or-laterPHP Since Dec 14Pushed 2y ago1 watchersCompare [ Source](https://github.com/bristol-su/nus-unioncloud-api-wrapper)[ Packagist](https://packagist.org/packages/twigger/unioncloud)[ RSS](/packages/twigger-unioncloud/feed)WikiDiscussions master Synced 6d ago READMEChangelog (10)Dependencies (5)Versions (17)Used By (1) PHP UnionCloud API Wrapper ========================== [](#php-unioncloud-api-wrapper) Toby Twigger () on behalf of Bristol SU (). [![Scrutinizer Code Quality](https://camo.githubusercontent.com/2ad5bd1ca5cf869fd726ee32e2d91ac5a2a89d1bd7ba7ee68fe4cbddd7d322c4/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f746f6279747769676765722f6e75732d756e696f6e636c6f75642d6170692d777261707065722f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/tobytwigger/nus-unioncloud-api-wrapper/?branch=master)[![Build Status](https://camo.githubusercontent.com/31ec83e4a828ce0cd4a5b2c7fe95a62bdd90b607ea91c07c35ea70f95d93d878/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f746f6279747769676765722f6e75732d756e696f6e636c6f75642d6170692d777261707065722f6261646765732f6275696c642e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/tobytwigger/nus-unioncloud-api-wrapper/build-status/master) Installation ------------ [](#installation) Add `twigger/unioncloud` as a require dependency in your `composer.json` file: ``` composer require twigger/unioncloud ``` Require composer's autoload, and point your scripts to the UnionCloud namespace ``` use \Twigger\UnionCloud\API\UnionCloud as UnionCloudWrapper ``` ### Laravel [](#laravel) Support for Laravel is supplied out of the box #### Configuration [](#configuration) Publish the UnionCloud configuration ``` php artisan vendor:publish --provider="Twigger\UnionCloud\API" ``` Add the following to your .env file ``` AUTHENTICATOR=v0 UNIONCLOUD_BASEURL=bristol.unioncloud.org UNIONCLOUD_V0AUTH_EMAIL=myEmail UNIONCLOUD_V0AUTH_PASSWORD=myPassword UNIONCLOUD_V0AUTH_APPID=appID UNIONCLOUD_V0AUTH_APPPASSWORD=appPassword ``` If you're using the version 1 authentication (AWS), you will instead need the following: ``` AUTHENTICATOR=v1 UNIONCLOUD_BASEURL=api.unioncloud.org UNIONCLOUD_V1_ACCESS_KEY=ACCESS_KEY UNIONCLOUD_V1_SECRET_KEY=API_SECRET UNIONCLOUD_V1_API_KEY=APIKEY ``` If you're using Laravel <5.5, you'll also need to register the service provider in the `providers` array in `config/app.php` ``` Twigger\UnionCloud\API\UnionCloudServiceProvider::class ``` To resolve the UnionCloud instance from the Laravel service container ``` $unionCloud = resolve('Twigger\UnionCloud\API\UnionCloud'); ``` This will be set with your authentication parameters and base URL. Usage ----- [](#usage) ### Setup [](#setup) Create a new UnionCloud Wrapper: ``` $unionCloud = new UnionCloudWrapper($auth); ``` This takes an associative array of authentication parameters. For example, ``` $auth = [ 'email'=>'tt15951@bristol.ac.uk', 'password'=>'top_secret', 'appID'=>'MyAppID', 'appPassword'=>'myPass' ]; ``` Set all relevant global configuration values. These are currently the base URL and the debug option. - The base URL is in the format `'bristol.unioncloud.org'`. - Debug will return information about the raw request and response. You may still access meta data (such as the status code) out of debug mode. ``` $unionCloud->setBaseURL('union.unioncloud.org') ; $unionCloud->debug(); ``` ### Making Requests [](#making-requests) Any requests made take the following format: - Resource to interact with - Request specific configurations - Specific API call to make - Format to receive the data in If your IDE supports DocBlocks, you should have hints at all available resources and methods. #### Resource to interact with [](#resource-to-interact-with) These take the plural form of the resource name in camelCase. For example, ``` users() userGroupMemberships() ``` A resource specific request class will be returned, containing all methods available to that resource. #### Request specific configurations [](#request-specific-configurations) This allows you to change the specifics of your API call. The following methods are available ``` setMode($mode) // Takes basic, standard or full. Defaults to full paginate() setPage($page) ``` - `setMode()` allows you to alter the mode you make the request in. UnionCloud takes `basic|standard|full` as options. Defaults to full. - `paginate()` should be used to enable the pagination functions. -`setPage` may be used alongside `paginate()` to retrieve a specific page. This, however, will rarely be used since the default page is `1`. #### Specific API call [](#specific-api-call) You may now make a call to the correct API endpoint. The Request class contains instructions for the BaseRequest class as to how to create the API request. For example, you may call the `search()` function in the UserRequest class. This takes an array of parameters to search by. Look at your IDE hints to determine which methods are available to you. #### Format to recieve the response in [](#format-to-recieve-the-response-in) To make interacting with UnionCloud as simple as possible, you may request different types of response class. You may recieve one of the following: - Request Class - If you use the paginate() function, you will recieve a request class, however the function getResponse() will return the saved response. See the pagination section for more details. - Response Class - This is the normal response method. This returns a class with a load of information about the request, such as the status code, page numbers etc. If debugging is turned on, this class also holds information about the request made. - Use the get() function to retrieve the data from the response class. This will be given in a ResourceCollection class. - ResourceCollection class - A Resource Collection is simply a collection of resources. We use a custom collection class to introduce useful features for manipulating responses. - For example, you may use the first() function to get the first resource returned. - Resource Class - This is the class in which the data for a resource is held. For example, there is a User Resource class, which contains information about the user. #### Chaining [](#chaining) In order to achieve clean code, chaining is allowed. The following line will search for a user called `Toby` and return the first user as a UserResource class. We assume $unionCloud contains a UnionCloud class which has the correct authentication parameters passed. ``` $user = $unionCloud->users()->search(['forename'=>'Toby'])->get()->first(); ``` We could also specify the mode to search by. ``` $user = $unionCloud->users()->setMode('basic')->search(['forename'=>'Toby'])->get()->first(); ``` Or if we wanted to check the request was successful: ``` if($unionCloud->users()->setMode('basic')->getByUID('1234567')->getStatusCode() === 200) { // Request was successful } ``` ### Using ResourceClasses [](#using-resourceclasses) To make developing with UnionCloud easier, we provide data in a ResourceClass. There is a ResourceClass per resource, which may contain helpful functions to interact with that resource. For example, the UserResource class may contain a function called isOver18(), which will check if the user is over 18. To access variables present in a resource class, just treat them as class properties. Given $user contains a populated UserResource class, the following may be used to look at information about a particular user ``` $user->forename $user->dob ... ``` ### Casting [](#casting) To further improve workflows, we automatically cast certain parameters to a specific type. For example, a date field will be shows as a Carbon instance, and a name field will be correctly capitalised. #### Basic Casting [](#basic-casting) You don't have to worry about casting manually unless you're developing or modifying a Resource class. In the Resource class, there is a variable called $casts. This defines the resource attribute keys, and the format we should cast it to. Currently the available options are - date (Carbon Instance) - properCase (Format a name) - `AnotherResourceClass::class` `AnotherResourceClass::class` allows us to cast specific return attributes into alternate Resource classes. Say a user has a UserGroup Membership attribute returned, which contains an array of UserGroup Memberships. We may speficy the usergroup membership attribute should be casted into a UserGroup Memberhip Resource class by setting `$casts` to the following. ``` $casts = [ 'userGroupMemberships' => UserGroupMembershipResource::class ]; ``` We will pass each usergroup membership into the resource constructor to produce a resource class for each membership. Always use camelCase for specifying attributes! #### Advanced Casting [](#advanced-casting) For some API calls, two or more resources are returned in the same array. For example, the following may be returned: ``` $event = [ 'user_uid' => 22222, 'user_forename' => 'Toby', 'event_id' => 3848, `event_name` => `Event the user 22222 set up` ]; ``` In this case, use the $customCasts array. Each key should contain the new attribute you want to create and the new resource class to insert into that attribute, seperated with a pipe. The value should be an array of mappings, from the current attributes to the new resource attributes. In the above example, if we wanted the data to look like ``` $event = [ 'setup_user' => UserResource[ 'uid' => 22222, 'forename' => 'Toby' ]. 'event_id' => 3848, 'event_name' => 'Event the user 22222 set up' ]; ``` we could specify the following cast ``` $customCasts = [ 'setup_user|'.UserResource::class => [ 'user_uid' => 'uid', 'user_forename' => 'forename' ], ... ]; ``` ### Pagination [](#pagination) Pagination only applies if the API has been set up to handle pagination. By this, we mean in the API Instructions (the method in the specific Request Class), the function $this->enablePagination() has been called. The developer using this repo must also request pagination functionality for each api call. This can be done by, for example ``` $users = $unionCloud->users()->paginate()->search(['forename', 'Toby']) ``` This will return a UserRequest class. The following methods are now available to be used: ``` $users->getResponse(); // Get the UserResponse class for the first page $users->getAllPages(); // Return a collection containing all users. This will iterate through pages until the final page is reached, so may take a while (although syncronous requests are coming!) $users->next(); // Return the RequestClass containing the response to the next page. $users->previous(); // Return the RequestClass containing the response to the previous page. ``` Contributing ============ [](#contributing) This is an unfinished repository, any any contributions would be welcomed! The following is an incomplete list of things to be done. - Most the request classes have to be populated with their methods - Most the resource classes have to be populated with casting information and useful resource specific functions. - An authenticator for AWS needs to be written Repository Documentation ======================== [](#repository-documentation) The automatically generated phpDocumentor documentation may be found on Github Pages [phpDoc Documentation](https://tobytwigger.github.io/nus-unioncloud-api-wrapper/) ### Health Score 32 — LowBetter than 72% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity15 Limited adoption so far Community13 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 87.5% 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 ~96 days Recently: every ~181 days Total 14 Last Release 1453d ago Major Versions v0.2 → v1.02019-08-29 ### Community Maintainers ![](https://www.gravatar.com/avatar/94c469b6466204c9a4091dde7d1b4a1a37810daee22bf88d16a800dbdb23a205?d=identicon)[tt15951](/maintainers/tt15951) --- Top Contributors [![tobytwigger](https://avatars.githubusercontent.com/u/24829185?v=4)](https://github.com/tobytwigger "tobytwigger (14 commits)")[![AidanLaycock](https://avatars.githubusercontent.com/u/21222371?v=4)](https://github.com/AidanLaycock "AidanLaycock (1 commits)")[![scrutinizer-auto-fixer](https://avatars.githubusercontent.com/u/6253494?v=4)](https://github.com/scrutinizer-auto-fixer "scrutinizer-auto-fixer (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/twigger-unioncloud/health.svg) ``` [![Health](https://phpackages.com/badges/twigger-unioncloud/health.svg)](https://phpackages.com/packages/twigger-unioncloud) ``` ### Alternatives [statamic/cms The Statamic CMS Core Package 4.8k3.2M720](/packages/statamic-cms)[ashallendesign/laravel-exchange-rates A wrapper package for interacting with the exchangeratesapi.io API. 485677.8k](/packages/ashallendesign-laravel-exchange-rates)[tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3731.2M42](/packages/tencentcloud-tencentcloud-sdk-php)[vluzrmos/slack-api Wrapper for Slack.com WEB API. 102589.1k3](/packages/vluzrmos-slack-api)[smodav/mpesa M-Pesa API implementation 16363.7k1](/packages/smodav-mpesa)[keboola/storage-api-client Keboola Storage API PHP Client 10387.5k25](/packages/keboola-storage-api-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)