PHPackages                             shaunpersad/api-foundation - 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. shaunpersad/api-foundation

ActiveLibrary[Authentication & Authorization](/categories/authentication)

shaunpersad/api-foundation
==========================

This is a package for Laravel 4 that provides a basis for creating APIs. Particularly, it allows for OAuth 2.0 implementation using any grant type your application requires, including custom grant types. Additionally, it also standardizes all API responses into an easily definable format.

0.1.6(11y ago)561MITPHPPHP >=5.4.0

Since Jun 24Pushed 11y ago1 watchersCompare

[ Source](https://github.com/shaunpersad/api-foundation)[ Packagist](https://packagist.org/packages/shaunpersad/api-foundation)[ Docs](https://github.com/shaunpersad/api-foundation)[ RSS](/packages/shaunpersad-api-foundation/feed)WikiDiscussions master Synced 5d ago

READMEChangelog (7)Dependencies (5)Versions (8)Used By (0)

0.1.6 Notes
-----------

[](#016-notes)

Version 0.1.6 adds support for signing in with Google+. Note, however, that you do not need to be an actual Google+ user to sign in using Google+. You simply need a Google account of any kind. There are two supported ways to implement this in your app: the recommended hybrid server-side flow using a server code:  and the pure server-side flow: .

The hybrid server-side flow is supported in Api Foundation via the gplus\_server\_code Grant Type, where you must pass a gplus\_server\_code parameter which is the "one-time authorization code" specified in Google's documentation.

The pure server-side flow corresponds to the gplus\_access\_token Grant Type, where you must pass a gplus\_access\_token parameter which is an access\_token gotten by any other means from Google.

---

This version also adds further flexibility by adding in new config options to specify database field names specific to your app.

Note: if you are upgrading from a previous version of this package, please add a field in your users table that will be used as the Google+ user id. If you are using our original migrations, you can simply run >php artisan migrate --package="shaunpersad/api-foundation" to add in the field automatically.

Introduction
------------

[](#introduction)

This is a package for Laravel 4 that provides a basis for creating APIs. Particularly, it allows for OAuth 2.0 implementation using any Grant Type your application requires, including custom Grant Types.

Additionally, it also standardizes all API responses into an easily definable format.

Key Concepts
------------

[](#key-concepts)

- **Authorization**: A user must give permission for an app to access their resources on the resource server. E.g. When logging in to an app via Facebook, you are giving that app permission to access your resources on Facebook.
- **Authorization Code**: After a successful Authorization process, an Authorization Code is returned. This code can then be exchanged for an Access Token.
- **Access Token**: A token presented when accessing a protected resource. Often, this Access Token acts on behalf of a specific user in your system (however this does not always have to be the case).
- **Authentication**: Making a request for an Access Token. The structure and requirements for this request are based on the Grant Types implemented by the app.
- **Grant Type**: The Authentication method used. ApiFoundation implements multiple Grant Types, and allows for custom Grant Types to be created.
- **Client**: An app that is using your API. It can be anything: a website, mobile app, or a server. "Client" and "app" will be used interchangeably in this doc.
- **Client ID**: Used to identify an app.
- **Client Secret**: A password used to verify the client. Optional, and, according to OAuth 2.0, MUST be excluded if this secret is at risk of being exposed publicly.

OAuth 2.0 in ApiFoundation
--------------------------

[](#oauth-20-in-apifoundation)

OAuth 2.0 support is built on top of bshaffer's Oauth2 Server Library for PHP:

For excellent descriptions of OAuth 2.0 and how it is implemented, please check out his documentation.

As a high-level introduction to how OAuth 2.0 is used in ApiFoundation, essentially there is a "Token" endpoint where, given particular parameters (such as a user's username and password), returns an Access Token which (usually) maps directly to a user and can then be used to authenticate future API requests.

Those particular parameters are determined by which Grant Type you choose to use in your API. There are several Grant Types to choose from:

- **Authorization Code**: this is the standard OAuth 2.0 implementation. If you've ever used Facebook's Graph API OAuth 2.0 implementation, this is essentially that flow, where a user is directed to a login screen where they can log in to your system somehow and then authorize an app. Doing so returns an Authorization Code (which, remember, is not the same as an Access Token!). This Authorization Code can then be sent to your API's Token endpoint to receive an Access Token.
- **Password (User Credentials)**: simpler implementation, where the user's username and password are sent to the Token endpoint directly to receive an Access Token. This is the most convenient way to authenticate a user.
- **Client Credentials**: the app's Client ID and Client Secret are sent to the Token endpoint to receive an Access Token. This Access Token does not map to a user, however. In essence, this is the app itself using the API, with access only to the resources under the app's control (as opposed to those accessible to a user).
- **Refresh Token**: A "Refresh Token" is sent back along with the Access Token when a user is authenticated via the Authorization Code or Password Grant Types. This Refresh Token can then be sent back to the Token endpoint for a fresh Access Token.
- **Implicit**: This is the same as the Authorization Code Grant Type, except instead of the Authorization Code being returned when a user logs in to your system, the Access Token is returned directly. This would typically be the preferred method when using the API in front-end JavaScript.
- **Facebook Access Token (Custom Grant Type)**: You may create your own Grant Types. One such custom Grant Type is the "Facebook Access Token" Grant Type, which allows you to send a Facebook access token to the Token endpoint to receive an Access Token. In other words, it exchanges a Facebook access token (which identifies a FACEBOOK user) for one of your resource server's Access Tokens (which identifies one of YOUR users). So, if your app has a "login with Facebook" feature, the access token returned by Facebook at the end of the Facebook auth flow can then be used to create and/or identify a user in your system.

Supporting multiple Grant Types means that your API can be used in numerous situations while still providing a secure method for access, including in mobile apps, in front-end JavaScript, or even completely server-side.

Installation
------------

[](#installation)

You may use ApiFoundation with new projects or existing, however existing projects will require some modification. We will start with the steps for a new project first.

### New Project Installation

[](#new-project-installation)

Install via composer.

> require: "shaunpersad/api-foundation": "0.1.6"

Add the service provider to your list of providers in `app/config/app.php`:

> 'Shaunpersad\\ApiFoundation\\ApiFoundationServiceProvider'

Publish the included config file, to make it available to your project for modification:

> php artisan config:publish shaunpersad/api-foundation

This copies the config file to `app/config/packages/shaunpersad/api-foundation`

Run the included migrations (Note: this will create a "users" table):

> php artisan migrate --package="shaunpersad/api-foundation"

This is an included database seeder which you may wish to use as a basis for your own seeder: `shaunpersad/api-foundation/src/Shaunpersad/ApiFoundation/Database/OAuthSeeder.php`

The config file and the created tables are designed to work together out of the box, however should you choose to modify the users table, please check the config file to make sure you change the appropriate values.

Also, if you plan to utilize Facebook integration, please set a Facebook App ID and a Facebook App Secret in the config file.

Find the included `sample-routes.php` file: `shaunpersad/api-foundation/src/Shaunpersad/ApiFoundation/sample-routes.php`

In it, you will find the various routes you may wish to implement, which will be described in further detail in the "Endpoints" section. Copy these routes into your project.

### Existing Project Installation

[](#existing-project-installation)

Install via composer.

> require: "shaunpersad/api-foundation": "0.1.6"

Add the service provider to your list of providers in `app/config/app.php`:

> 'Shaunpersad\\ApiFoundation\\ApiFoundationServiceProvider'

Publish the included config file, to make it available to your project for modification:

> php artisan config:publish shaunpersad/api-foundation

If you already have your own "users" table, DO NOT run the included migrations. Instead, create your own migration, then find the included create\_oauth\_tables migration file (`shaunpersad/api-foundation/src/migrations/`) and copy the code into your own migration file, then run this migration.

This is an included database seeder which you may wish to use as a basis for your own seeder: `shaunpersad/api-foundation/src/Shaunpersad/ApiFoundation/Database/OAuthSeeder.php`

If you are using your own "users" table, then you will likely need to modify the config file to point ApiFoundation to the correct fields in your users table. Note: you will need to have a field that corresponds to a "username", e.g. an email address or an actual username. You will also need to have a password field.

Also, if you plan to utilize Facebook integration, please set a Facebook App ID and a Facebook App Secret in the config file.

Next, you may need to extend the class that controls how ApiFoundation interacts with your database: ModelStorage. While technically you may override any and all methods, you should only have to override a select few to suit your needs:

- > checkUserCredentials ($username, $password):bool

    This accepts the user's username and raw password, and then checks that the password is valid.
- > getUserInfoByUsername ($username):array

    Given a user's username, gets the user's info (typically a database row) as an associative array with a MANDATORY user\_id key.
- > checkPassword ($username, $password):bool

    This is by default used by the checkUserCredentials method. You may override this if you are using a custom Auth method.
- > getUserInfoByFacebookId ($facebook\_id):array

    Given a user's facebook id, gets the user's info (typically a database row) as an associative array with a MANDATORY user\_id key.
- > createFacebookUser (GraphUser $facebook\_user):void

    Creates a new user in your system based on their Facebook information.

If using Facebook integration, you may also need to extend the FacebookAccessToken Grant Type if you wish to control exactly how a Facebook access token gets exchanged for one of your Access Tokens. For example, if you do not wish to use the Facebook user's email address as their username.

In order to use your extended ModelStorage and/or FacebookAccessToken classes, you must also override the relevant IoC bindings, which may include `oauth2`, `oauth2_grant_types`, and/or `oauth2_storage` (see the "IoC Bindings" section).

Find the included `sample-routes.php` file: `shaunpersad/api-foundation/src/Shaunpersad/ApiFoundation/sample-routes.php`

In it, you will find the various routes you may wish to implement, which will be described in further detail in the "Usage" section. Please read through the comments for each route as you implement them.

Endpoints
---------

[](#endpoints)

The `sample-routes.php` file contains several routes which can be identified as the following kinds of API endpoints:

### The Authorize endpoint

[](#the-authorize-endpoint)

In the `sample-routes.php file`, this is the `/authorize` route. This endpoint is used with the Authorization Code Grant Type. A GET request to this endpoint should display a form or other method for a user to log in to your system. A POST request to this endpoint should process the login and redirect the user to either a specified "redirect\_uri" or back to the form with an error message. If the user is redirected to the "redirect\_uri", that URI should also contain either the Authorization Code ("code" query param), or the Access Token in the URL fragment if the Grant Type is "Implicit".

### The Token endpoint

[](#the-token-endpoint)

In the `sample-routes.php` file, this is the `/api/v1/get-token` route. This is the endpoint that, based on whichever Grant Type you are using, particular parameters are sent and an Access Token is received.

\#####Required Parameters

- `client_id` - must be present either in the body of the request or in the Authorize HTTP Header (Http Basic).
- `grant_type` - must be present in the body of the request, and set to one of your Grant Types.

    The value of this param maps to one of the described Grant Types via the `oauth2_grant_types` IoC binding in the ApiFoundationServiceProvider. The default mapping is as follows, where the key is what you'd use as the `grant_type` value:

    ```
            return array(
                'authorization_code' => '\OAuth2\GrantType\AuthorizationCode',
                'password' => '\OAuth2\GrantType\UserCredentials',
                'client_credentials' => '\OAuth2\GrantType\ClientCredentials',
                'refresh_token' => '\OAuth2\GrantType\RefreshToken',
                'fb_access_token' => '\Shaunpersad\ApiFoundation\OAuth2\GrantType\FacebookAccessToken',
                'gplus_access_token' => '\Shaunpersad\ApiFoundation\OAuth2\GrantType\GPlusAccessToken',
                'gplus_server_code' => '\Shaunpersad\ApiFoundation\OAuth2\GrantType\GPlusServerCode',
            );

    ```

    Of this list, the Grant Types you wish to support may be defined in the config file. To add additional Grant Types, you will need to override the `oauth2_grant_types` binding by defining your own binding with the same key.
- `client_secret` - should only be present if your app uses one. Apps should not use Client Secrets if it can be exposed publicly. If a Client Secret is used, it must be present and must be either in the body of the request or in the Authorize HTTP Header (Http Basic).

### The Redirect endpoint

[](#the-redirect-endpoint)

In the `sample-routes.php` file, this is the `/login-redirect` route. This is the URI that you'd want the user to be redirected to after being authorized through the Authorize endpoint.

### Resource endpoint

[](#resource-endpoint)

In the `sample-routes.php` file, this is the `/api/v1/me` route. This is an example of an API resource. Passing a valid Access Token to this route will return that authenticated user ("me") as a resource.

### Facebook routes

[](#facebook-routes)

There are two additional routes included to demonstrate the Facebook Access Token Grant Type. With the Facebook App ID and Secret supplied in the config file, the `/get-facebook-login` route will redirect you to Facebook to log in and authorize your app. After authorizing, Facebook will redirect you to the `/facebook-login-redirect` route, and display your Facebook access token. This Facebook access token can then be sent to the Token endpoint to exchange for one of your app's Access Tokens.

### Google+ routes

[](#google-routes)

There are three additional routes included to demonstrate the two Grant Types associated with Google+, corresponding to the two possible Google+ login flows. With the Google Client ID and Secret supplied in the config file, the `/get-gplus-login` route will redirect you to Google to log in and authorize your app. After authorizing, Google will redirect you to the `/gplus-login-redirect` route, and display your Google+ access token. This Google+ access token can then be sent to the Token endpoint to exchange for one of your app's Access Tokens.

IoC Bindings
------------

[](#ioc-bindings)

- **oauth2** - a *singleton* which is the underlying OAuth 2.0 server object made by bshaffer's Oauth2 Server Library: . This is used internally in the ApiFoundationServiceProvider, so you generally should not need to interact with this.
- **oauth2\_grant\_types** - a *singleton* which creates an associative array mapping of `grant_type` to classes that implement that grant\_type. You must override this binding with your own if you wish to use your own custom grant types.
- **oauth2\_storage** - a *singleton* which creates an object to handle interaction with the database. You must override this binding with your own if you wish to use your own custom storage.
- **requires\_oauth\_token** - a *filter* which restricts routes to requiring a valid Access Token (as the "access\_token" param). See the usage in the `sample-routes.php` file.
- **authorize\_request** - a *binding* which creates a request for the Authorize endpoint. You should pass in a "validate\_error\_callback" and a "validate\_success\_callback" to this when creating. This binding will likely only be used once. See the usage in the `sample-routes.php` file.
- **authorize\_response** - a *binding* which creates a response for a request to the Authorize endpoint. You should pass in the "is\_authorized" parameter to indicate whether or not the user authorized your app, as well as the "user\_id" parameter to indicate which user (if any) committed this action. This binding will likely only be used once. See the usage in the `sample-routes.php` file.
- **token\_response** - a *binding* which creates a response for the Token endpoint. This response will include either an Access Token, or error information. This binding will likely only be used once. See the usage in the `sample-routes.php` file.
- **api\_response\_array** - a *binding* which creates the structure for every API response. This structure can be changed by simply extending our service provider and overriding the makeAPIResponseArray method.
- **access\_token\_data** - an *instance* available after successful authentication via the requires\_oauth\_token filter. Contains Access Token data. You generally won't need to use this.
- **oauth2\_storage** - a *singleton* which creates an instance of Google\_Client, required to handle the underlying Google+ auth.

Helper Classes
--------------

[](#helper-classes)

- **SuccessResponse** - Use SuccessResponse::make($object) to create a JSON response for successful API requests. $object can be anything that would ordinarily be serializable by Laravel, such as an Eloquent Model.
- **ErrorResponse** - Use ErrorResponse::make($message, $status, $headers) to create a JSON response for API errors.
- **OAuthRequest** - Used to bridge between bshaffer's Oauth2 Server Library's Request objects and Laravel's.
- **OAuthResponse** - Used to bridge between bshaffer's Oauth2 Server Library's Response objects and Laravel's.

All of the response objects utilize the structure defined by the api\_response\_array binding.

Examples
--------

[](#examples)

For reproducibility, all examples shown have the following assumptions:

- installation of this package in a brand new project
- you have seeded the database with the data in the included seeder
- you have copied all the routes from `sample-routes.php` into your routes
- the base URL is
- the Token endpoint is a POST
- the client secret is not used
- the client id is passed in the request body (although in the headers is preferred)

### Using Authorization Code Grant Types

[](#using-authorization-code-grant-types)

In your browser, navigate to . You should get an error, as the comments in the `sample-routes.php` file state that:

You must also have the `response_type`, `client_id`, `state`, and `redirect_uri` set in the URL query, with `response_type` = "code" if not implicit (`token` if implicit) `client_id` = your client id, `state` = any random thing, `redirect_uri` = a valid redirect\_uri from the database.

With the data from the included seeder, `client_id` = "testclient", `redirect_uri` = "" Including these in the URL query will cause the login form will be displayed properly.

> e.g. [http://apitest.local/authorize?client\_id=testclient&response\_type=code&redirect\_uri=http://apitest.local/login-redirect&state=sdjf](http://apitest.local/authorize?client_id=testclient&response_type=code&redirect_uri=http://apitest.local/login-redirect&state=sdjf)

For error checking, try removing parameters.

Authorize the app by clicking the "yes" button, with valid credentials. If using the included seeder, `admin@local.com` and `password` should suffice. You should then be redirected to the redirect\_uri supplied, with the `code` parameter in the URL as your Authorization Code, or the `access_token` parameter in the URL fragment as your Access Token if the `response_type` parameter was set to `token`.

If you received an Authorization Code, you may then POST it (along with the other required params) to the Token endpoint to receive an Access Token

e.g. (Using CocoaRestClient):

### Using the Password Grant Type

[](#using-the-password-grant-type)

POST the required credentials and other params:

### Using the Facebook Access Token Grant Type

[](#using-the-facebook-access-token-grant-type)

In your browser, navigate to

You should be redirected to Facebook to log in and authorize the app. Once you have authorized or if you have previously authorized the app, you will be redirected back to , and your Facebook Access Token will be displayed.

You may then POST it (along with the other required params) to the Token endpoint:

### Accessing resources using Access Tokens

[](#accessing-resources-using-access-tokens)

POST to the "me" endpoint with a valid Access Token:

1. the seeded user:
2. the facebook user:

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

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 ~10 days

Total

7

Last Release

4283d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1702976?v=4)[Shaun Persad](/maintainers/shaunpersad)[@shaunpersad](https://github.com/shaunpersad)

---

Tags

apilaraveloauthapi foundation

### Embed Badge

![Health badge](/badges/shaunpersad-api-foundation/health.svg)

```
[![Health](https://phpackages.com/badges/shaunpersad-api-foundation/health.svg)](https://phpackages.com/packages/shaunpersad-api-foundation)
```

###  Alternatives

[auth0/login

Auth0 Laravel SDK. Straight-forward and tested methods for implementing authentication, and accessing Auth0's Management API endpoints.

2745.0M3](/packages/auth0-login)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)