A little over 3 years ago, Stormpath introduced PHP support for User Management and the response from the PHP community has been overwhelming and so supportive. Thank you! Since then, we have been working very hard on the PHP SDK to make it your go-to service for User Identity.
Today, we are happy announce that a stable version of the PHP SDK is being released to General Availability. Begone Beta Tag!
This release includes many changes: we removed the dependency on PEAR and now support installation using Packagist. Composer and Packagist gives us nice autoloader options, both of which uses the PHP Standards Recommendations (PSR). The PHP SDK has been updated to use PSR-4 autoloading from the deprecated PSR-0.
What’s New in the Stormpath PHP SDK?
Removing the PEAR Dependency
PEAR (PHP Extension and Application Repository) was introduced into PHP in 1999 by Stig Bakken to help promote the use of reusable PHP components. It is now 16 years old, and though still a useful component manager and actively supported, PEAR is not as simple as other options out there.
Terry Chay also stated it well on Twitter a few weeks ago while talking about PEAR.
The burning realization that you should have stopped
depending on #PEAR
#PHP packages 2 years ago…
#composer
— terry chay (@tychay)
November 5, 2015
The most actively used dependency manager is now Composer, so we wanted to make the integration of Composer much simpler and easier to use. Thank you to the many people who offered this feedback. We heard you loud and clear!
Moving to Composer and Packagist PHP Package Manager
Packagist is currently the most common PHP package manager and offers many different packages to include in your project. Many of our PHP users are fans, and better support for it was one of the main reasons we moved away from using PEAR.
During our beta period, you could install our PHP SDK with Packagist using Composer, but it required some modifications to your composer.json file.
Because we had the beta flag as part of our releases to Packagist, you had to have your minimum-stability set to ‘beta’ to install. If you did not do this, you would have to add in PEAR as a repository, and who remembers what that looks like? It would make for a messy Composer file, and would cause issues during updates.
The move to Packagist was pretty simple since we had been developing on the 1.x branch of the package already and it was enabled inside of Packagist.
PHP Feature Parity with the REST API
The biggest part of this GA release was getting the PHP SDK up to parity with the Stormpath REST API. The new ‘Organization’ endpoint is supported, and support for ID Site is brought up to par. JSON Web Tokens and OAuth Tokens are now supported (learn more about Token Authentication with Stormpath).
If we had just made a GA release of the PHP SDK back a few months ago, we would not have been able to release some of the code as it would have introduced backwards incompatible changes to the 1.x release. The changes that are left to give us 100% parity will be backwards compatible, which will be easier on our active users.
How to Install the Stormpath PHP SDK Now
The first thing to understand is that we now have dependencies inside of the SDK. These dependencies help with our JWTs for ID Site and OAuth Tokens and Guzzle which helps our HTTP calls to the API. These dependencies require you to use Composer to install the PHP SDK so you don’t have to worry about installing it manually.
Make Sure Composer is Installed
The first step is to ensure you have Composer installed. You can do so by running which composer in your terminal. You are ready to install the PHP SDK if this returns a path such as /usr/local/bin/composer.
Initialize Composer
Next, from within your projects root, initialize your Composer instance. If you have a composer.json file in your project root, you can skip this step. Run composer init from the project root and follow the prompts. I usually suggest to skip the part that asks you if you want to specify your dependencies and deal with them later.
Require the Stormpath PHP SDK
Once the composer.json file exists, run composer require stormpath/sdk from terminal in your projects root. This will update your Composer file to include the most recent stable release of the PHP SDK, which is now using Packagist.
You are now ready to begin using the PHP SDK!
What Is PSR-4 and Why Use It?
PSRs are a set of PHP Standards Recommendations created by a group of members of the PHP Framework Interop Group in 2009 at the php[tek] conference. The group was set up to work together and talk about commonalities between their projects.
The first PSR, PSR-0, is the standard for describing how autoloading would work to maintain interoperability with the projects. PSR-0 became an integral part of Composer and made it so you didn’t have to create your own autoloaders inside your project. Composer did it for you. Stormpath’s PHP SDK began using PSR-0 during the first release of the 1.x series. Since then, the PSR has been deprecated for an improved version of the autoloader: PSR-4.
Migrating from PSR-0 to PSR-4
When you update your SDK from <= 1.11.x@beta to 1.12.0, you will notice a lot of changes related to where files are being stored. Do not let this scare you! You can still easily update our SDK in your project (or migrate your own project).
If you look at our old code structure, everything was in a namespace folder named Stormpath that lived under the src directory. This was required for PSR-0 to work according to spec.
We have removed the Stormpath directory, which not only cleans up our directory structure, but also allows for PSR-4 to be implemented.
What’s Next for the PHP SDK?
We have come a long way since the start of the PHP SDK and are happy to finally provide you with a stable release. We have begun the implementation of PSR standards set out by PHP-FIG and will continue to implement them into the PHP SDK to make sure full interoperability amongst other projects that follow these standards recommendations.
Additionally, we’re continuing to extend PHP support into framework integrations, most recently Laravel, with more on the horizon. This release makes that work much easier.
Let Us Know What You Think
If you have any suggestions on features you would like to see in a future release, feel free to let us know with a
GitHub issue or reach out to support.
Of course, you can always reach me directly at brian@stormpath.com.