Download the PHP package maestrano/maestrano-php without Composer
On this page you can find all versions of the php package maestrano/maestrano-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download maestrano/maestrano-php
More information about maestrano/maestrano-php
Files in maestrano/maestrano-php
Package maestrano-php
Short Description Maestrano PHP Library
License MIT
Homepage https://maestrano.com
Informations about the package maestrano-php
Maestrano Cloud Integration is currently in closed beta. Want to know more? Send us an email to [email protected].
- Getting Setup
- Getting Started
- Installation
- Configuration
- Metadata Endpoint
- Single Sign-On Setup
- User Setup
- Group Setup
- Controller Setup
- Other Controllers
- Redirecting on logout
- Redirecting on error
- Account Webhooks
- Groups Controller
- Group Users Controller
- API
- Payment API
- Bill
- Recurring Bill
- Membership API
- User
- Group
- Connec!™ Data Sharing
- Making Requests
- Webhook Notifications
Getting Setup
Before integrating with us you will need an to create your app on the developer platform and link it to a marketplace. Maestrano Cloud Integration being still in closed beta you will need to contact us beforehand to gain production access.
We provide a Sandbox environment where you can freely launch your app to test your integration. The sandbox is great to test single sign-on and API integration (e.g: Connec! API). This Sandbox is available on the developer platform on your app technical page.
To get started just go to: https://developer.maestrano.com. You will find the developer platform documentation here: Documentation.
A php demo application is also available: https://github.com/maestrano/demoapp-php
Do not hesitate to shoot us an email at [email protected] if you have any question.
Getting Started
Installation
To install maestrano-php using Composer, add this dependency to your project's composer.json:
Then install via:
To use the bindings, use Composer's autoload:
Configuration
The developer platform is the easiest way to configure Maestrano. The only actions needed from your part is to create your application and environments on the developer platform and to create a config file or use environment variable to configure the SDK. The SDK will then contact the developer platform and retrieve the marketplaces configuration for your app environment.
A dev-platform.json
config file is loaded using:
The json file may look like this:
You can also use environment variables to configure your app environment:
To use configure the Developer Platform using environment variables, omit the file argument:
Single Sign-On Setup
It will require you to write a controller for the init phase and consume phase of the single sign-on handshake. You will receive 3 informations when logging in a user: the user, his group and the marketplace he's coming from.
You might wonder why we need a 'group' on top of a user. Well, Maestrano works with businesses and as such expects your service to be able to manage groups of users. A group represents 1) a billing entity 2) a collaboration group. During the first single sign-on handshake both a user and a group should be created. Additional users logging in via the same group should then be added to this existing group (see controller setup below).
For more information, please consult Multi-Marketplace Ingration.
User Setup
Let's assume that your user model is called 'User'. The best way to get started with SSO is to define a class method on this model called 'findOrCreateForMaestrano' accepting a Maestrano.Sso.User and aiming at either finding an existing maestrano user in your database or creating a new one. Your user model should also have a 'Provider' property and a 'Uid' property used to identify the source of the user - Maestrano, LinkedIn, AngelList etc..
Group Setup
The group setup is similar to the user one. The mapping is a little easier though. Your model should also have the 'Provider' property and a 'Uid' properties. Also your group model could have a AddMember method and also a hasMember method (see controller below)
Controller Setup
You will need two controller action init and consume. The init action will initiate the single sign-on request and redirect the user to Maestrano. The consume action will receive the single sign-on response, process it and match/create the user and the group.
The init action is all handled via Maestrano methods and should look like this:
For some reason, you may need to have a dynamic host where the consume request will be sent. You can use this method on the request object:
The default consume path will be appended appended to this host. (eg. http://consume.myapp.com/maestrano/auth/saml/consume.php?marketplace=maestrano
)
Based on your application requirements the consume action might look like this:
Note that for the consume action you should disable CSRF authenticity if your framework is using it by default. If CSRF authenticity is enabled then your app will complain on the fact that it is receiving a form without CSRF token.
Other Controllers
If you want your users to benefit from single logout then you should define the following filter in a module and include it in all your controllers except the one handling single sign-on authentication.
The above piece of code makes at most one request every 3 minutes (standard session duration) to the Maestrano website to check whether the user is still logged in Maestrano. Therefore it should not impact your application from a performance point of view.
If you start seing session check requests on every page load it means something is going wrong at the http session level. In this case feel free to send us an email and we'll have a look with you.
Redirecting on logout
When Maestrano users sign out of your application you can redirect them to the Maestrano logout page. You can get the url of this page by calling:
Account Webhooks
Single sign on has been setup into your app and Maestrano users are now able to use your service. Great! Wait what happens when a business (group) decides to stop using your service? Also what happens when a user gets removed from a business? Well the controllers describes in this section are for Maestrano to be able to notify you of such events.
Groups Controller (service cancellation)
Sad as it is a business might decide to stop using your service at some point. On Maestrano billing entities are represented by groups (used for collaboration & billing). So when a business decides to stop using your service we will issue a DELETE request to the webhook.account.groups_path endpoint (typically /maestrano/account/groups/:id).
Maestrano only uses this controller for service cancellation so there is no need to implement any other type of action - ie: GET, PUT/PATCH or POST. The use of other http verbs might come in the future to improve the communication between Maestrano and your service but as of now it is not required.
Group Users Controller (business member removal)
A business might decide at some point to revoke access to your services for one of its member. In such case we will issue a DELETE request to the webhook.account.group_users_path endpoint (typically /maestrano/account/groups/:group_id/users/:id).
Maestrano only uses this controller for user membership cancellation so there is no need to implement any other type of action - ie: GET, PUT/PATCH or POST. The use of other http verbs might come in the future to improve the communication between Maestrano and your service but as of now it is not required.
API
The maestrano package also provides bindings to its REST API allowing you to access, create, update or delete various entities under your account (e.g: billing).
Payment API
Bill
A bill represents a single charge on a given group.
Attributes
All attributes are available via their getter/setter counterpart. E.g:
Field | Mode | Type | Required | Default | Description |
---|---|---|---|---|---|
id | readonly | String | - | - | The id of the bill |
groupId | read/write | String | Yes | - | The id of the group you are charging |
priceCents | read/write | Integer | Yes | - | The amount in cents to charge to the customer |
description | read/write | String | Yes | - | A description of the product billed as it should appear on customer invoice |
createdAt | readonly | DateTime | - | - | When the the bill was created |
updatedAt | readonly | DateTime | - | - | When the bill was last updated |
status | readonly | String | - | - | Status of the bill. Either 'submitted', 'invoiced' or 'cancelled'. |
currency | read/write | String | - | AUD | The currency of the amount charged in ISO 4217 format (3 letter code) |
units | read/write | Float | - | 1.0 | How many units are billed for the amount charged |
periodStartedAt | read/write | DateTime | - | - | If the bill relates to a specific period then specifies when the period started. Both period_started_at and period_ended_at need to be filled in order to appear on customer invoice. |
periodEndedAt | read/write | Date | - | false | If the bill relates to a specific period then specifies when the period ended. Both period_started_at and period_ended_at need to be filled in order to appear on customer invoice. |
thirdParty | read/write | Boolean | - | - | Whether this bill is related to a third party cost or not. External expenses engaged for customers - such as paying a provider for sending SMS on behalf of customers - should be flagged as third party. |
Actions
List all bills you have created and iterate through the list
Access a single bill by id
Create a new bill
Cancel a bill
Recurring Bill
A recurring bill charges a given customer at a regular interval without you having to do anything.
Attributes
All attributes are available via their getter/setter counterpart. E.g:
Field | Mode | Type | Required | Default | Description |
---|---|---|---|---|---|
id | readonly | String | - | - | The id of the recurring bill |
groupId | read/write | String | Yes | - | The id of the group you are charging |
priceCents | read/write | Integer | Yes | - | The amount in cents to charge to the customer |
description | read/write | String | Yes | - | A description of the product billed as it should appear on customer invoice |
period | read/write | String | - | Month | The unit of measure for the billing cycle. Must be one of the following: 'Day', 'Week', 'SemiMonth', 'Month', 'Year' |
frequency | read/write | Integer | - | 1 | The number of billing periods that make up one billing cycle. The combination of billing frequency and billing period must be less than or equal to one year. If the billing period is SemiMonth, the billing frequency must be 1. |
cycles | read/write | Integer | - | nil | The number of cycles this bill should be active for. In other words it's the number of times this recurring bill should charge the customer. |
startDate | read/write | DateTime | - | Now | The date when this recurring bill should start billing the customer |
createdAt | readonly | DateTime | - | - | When the the bill was created |
updatedAt | readonly | DateTime | - | - | When the recurring bill was last updated |
currency | read/write | String | - | AUD | The currency of the amount charged in ISO 4217 format (3 letter code) |
status | readonly | String | - | - | Status of the recurring bill. Either 'submitted', 'active', 'expired' or 'cancelled'. |
initialCents | read/write | Integer | - | 0 | Initial non-recurring payment amount - in cents - due immediately upon creating the recurring bill |
Actions
List all recurring bills you have created:
Access a single bill by id
Create a new recurring bill
Cancel a bill
Membership API
User
A user is a member of a group having access to your application. Users are currently readonly.
Attributes
Field | Mode | Type | Required | Default | Description |
---|---|---|---|---|---|
id | readonly | String | - | - | The id of the user |
first_name | readonly | String | - | - | The user first name |
last_name | readonly | String | - | - | The user last name |
readonly | String | - | - | The user real email address | |
company_name | readonly | String | - | - | The user company name as it was entered when they signed up. Nothing related to the user group name. |
country | readonly | String | - | - | The country of the user in ISO 3166-1 alpha-2 format (2 letter code). E.g: 'US' for USA, 'AU' for Australia. |
created_at | readonly | DateTime | - | - | When the user was created |
updated_at | readonly | DateTime | - | - | When the user was last updated |
Actions
List all users having access to your application
Access a single user by id
Group
A group represents a customer account and is composed of members (users) having access to your application. A group also represents a chargeable account (see Bill/RecurringBill). Typically you can remotely check if a group has entered a credit card on Maestrano.
Groups are currently readonly.
Attributes
Field | Mode | Type | Required | Default | Description |
---|---|---|---|---|---|
id | readonly | String | - | - | The id of the group |
name | readonly | String | - | - | The group name |
readonly | string | - | - | The principal email address for this group (admin email address) | |
has_credit_card | readonly | Boolean | - | - | Whether the group has entered a credit card on Maestrano or not |
free_trial_end_at | readonly | DateTime | - | - | When the group free trial will be finishing on Maestrano. You may optionally consider this date for your own free trial (optional) |
currency | readonly | String | - | - | The currency used by this Group in ISO 4217 format (3 letter code) |
country | readonly | String | - | - | The country of the group in ISO 3166-1 alpha-2 format (2 letter code). E.g: 'US' for USA, 'AU' for Australia. |
city | readonly | String | - | - | The city of the group |
main_accounting | readonly | String | - | - | Main accounting package used by this group. Possible values: 'quickbooks', 'xero', 'myob' |
timezone | readonly | String | - | - | The group timezone in Olson format |
created_at | readonly | DateTime | - | - | When the group was created |
updated_at | readonly | DateTime | - | - | When the group was last updated |
Actions
List all groups having access to your application
Access a single group by id
Connec!™ Data Sharing
Maestrano offers the capability to share actual business data between applications via its data sharing platform Connec!™.
The platform exposes a set of RESTful JSON APIs allowing your application to receive data generated by other applications and update data in other applications as well!
Connec!™ also offers the ability to create webhooks on your side to get automatically notified of changes happening in other systems.
Connec!™ enables seamless data sharing between the Maestrano applications as well as popular apps such as QuickBooks and Xero. One connector - tens of integrations!
Making Requests
Connec!™ REST API documentation can be found here: http://maestrano.github.io/connec
The Maestrano API provides a built-in client - based on CURL - for connecting to Connec!™. Things like connection and authentication are automatically managed by the Connec!™ client.
Webhook Notifications
If you have configured the Maestrano API to receive update notifications from Connec!™ then you can expect to receive regular POST requests on the notification_path you have configured.
Notifications are JSON messages containing the list of entities that have recently changed in other systems. You will only receive notifications for entities you have subscribed to.
Example of notification message:
Entities sent via notifications follow the same data structure as the one described in our REST API documentation (available at http://maestrano.github.io/connec)
Support
This README is still in the process of being written and improved. As such it might not cover some of the questions you might have.
So if you have any question or need help integrating with us just let us know at [email protected]
License
MIT License. Copyright 2017 Maestrano Pty Ltd. https://maestrano.com
You are not granted rights or licenses to the trademarks of Maestrano.
All versions of maestrano-php with dependencies
ext-curl Version *
ext-json Version *
ext-mbstring Version *
nategood/httpful Version *
gilbitron/php-simplecache Version ~1.4