parse-php-sdk

[][open-collective-link] [][open-collective-link]

A library that gives you access to the powerful Parse Server backend from your PHP app. For more information on Parse and its features, see the website, the PHP guide, the Cloud Code guide or API Reference.

Table of Contents

• Compatibility
• Installation
  • Install with Composer
  • Install with Git
  • Install with another method
• Setup
  • Initializing
  • Server URL
  • Server Health Check
  • Http Clients
  • Alternate CA File
• Getting Started
  • Use Declarations
  • Parse Objects
  • Users
    • Session Id and Session Fixation
    • Verification Emails
  • ACLs
  • Queries
    • Aggregate
    • Distinct
    • Relative Time
  • Cloud Functions
  • Cloud Jobs
  • Config
  • Analytics
  • Files
  • Push
    • Push to Channels
    • Push with Query
    • Push with Audience
    • Push Status
  • Server Info
    • Version
    • Features
  • Schema
    • Index
    • Purge
  • Logs
• Contributing / Testing

Compatibility

The Parse PHP SDK is continuously tested with the most recent releases of PHP to ensure compatibility. We follow the PHP Long Term Support plan and only test against versions that are officially supported and have not reached their end-of-life date.

Installation

There are various ways to install and use this sdk. We'll elaborate on a couple here. Note that the Parse PHP SDK requires PHP 5.4 or newer. It can also run on HHVM (recommended 3.0 or newer).

Install with Composer

[Get Composer], the PHP package manager. Then create a composer.json file in your projects root folder, containing:

{
    "require": {
        "parse/php-sdk" : "1.5.*"
    }
}

Run "composer install" to download the SDK and set up the autoloader, and then require it from your PHP script:

require 'vendor/autoload.php';

Install with Git

You can clone down this sdk using your favorite github client, or via the terminal.

git clone https://github.com/parse-community/parse-php-sdk.git

You can then include the autoload.php file in your code to automatically load the Parse SDK classes.

require 'autoload.php';

Install with another method

If you downloaded this sdk using any other means you can treat it like you used the git method above. Once it's installed you need only require the autoload.php to have access to the sdk.

Setup

Once you have access to the sdk you'll need to set it up in order to begin working with parse-server.

Initializing

After including the required files from the SDK, you need to initialize the ParseClient using your Parse API keys:

ParseClient::initialize( $app_id, $rest_key, $master_key );

If your server does not use or require a REST key you may initialize the ParseClient as follows, safely omitting the REST key:

ParseClient::initialize( $app_id, null, $master_key );

Server URL

Directly after initializing the sdk you should set the server url.

// Users of Parse Server will need to point ParseClient at their remote URL and Mount Point:
ParseClient::setServerURL('https://my-parse-server.com:port','parse');

Notice Parse server's default port is 1337 and the second parameter parse is the route prefix of your parse server.

For example if your parse server's url is http://example.com:1337/parse then you can set the server url using the following snippet

ParseClient::setServerURL('https://example.com:1337','parse');

Server Health Check

To verify that the server url and mount path you've provided are correct you can run a health check on your server.

$health = ParseClient::getServerHealth();
if($health['status'] === 200) {
    // everything looks good!
}

If you wanted to analyze it further the health response may look something like this.

{
    "status"    : 200,
    "response"  : {
        "status" : "ok"
    }
}

The 'status' being the http response code, and the 'response' containing what the server replies with. Any additional details in the reply can be found under 'response', and you can use them to check and determine the availability of parse-server before you make requests.

Note that it is not guaranteed that 'response' will be a parsable json array. If the response cannot be decoded it will be returned as a string instead.

A couple examples of bad health responses could include an incorrect mount path, port or domain.

// ParseClient::setServerURL('http://localhost:1337', 'not-good');
{
    "status": 404,
    "response": "...Cannot GET \/not-good\/health..."
}

// ParseClient::setServerURL('http://__uh__oh__.com', 'parse');
{
    "status": 0,
    "error": 6,
    "error_message": "Couldn't resolve host '__uh__oh__.com'"
}

Keep in mind error & error_message may change depending on whether you are using the curl (may change across versions of curl) or stream client.

Http Clients

This SDK has the ability to change the underlying http client at your convenience. The default is to use the curl http client if none is set, there is also a stream http client that can be used as well.

Setting the http client can be done as follows:

// set curl http client (default if none set)
ParseClient::setHttpClient(new ParseCurlHttpClient());

// set stream http client
// ** requires 'allow_url_fopen' to be enabled in php.ini **
ParseClient::setHttpClient(new ParseStreamHttpClient());

If you have a need for an additional http client you can request one by opening an issue or by submitting a PR.

If you wish to build one yourself make sure your http client implements ParseHttpable for it be compatible with the SDK. Once you have a working http client that enhances the SDK feel free to submit it in a PR so we can look into adding it in.

Alternate CA File

It is possible that your local setup may not be able to verify with peers over SSL/TLS. This may especially be the case if you do not have control over your local installation, such as for shared hosting.

If this is the case you may need to specify a Certificate Authority bundle. You can download such a bundle from http://curl.haxx.se/ca/cacert.pem to use for this purpose. This one happens to be a Mozilla CA certificate store, you don't necessarily have to use this one but it's recommended.

Once you have your bundle you can set it as follows:

// ** Use an Absolute path for your file! **
// holds one or more certificates to verify the peer with
ParseClient::setCAFile(__DIR__ . '/certs/cacert.pem');

Getting Started

We highly recommend you read through the guide first. This will walk you through the basics of working with this sdk, as well as provide insight into how to best develop your project.

If want to know more about what makes the php sdk tick you can read our API Reference and flip through the code on github.

Check out the [Parse PHP Guide] for the full documentation.

Use Declarations

Add the "use" declarations where you'll be using the classes. For all of the sample code in this file:

use Parse\ParseObject;
use Parse\ParseQuery;
use Parse\ParseACL;
use Parse\ParsePush;
use Parse\ParseUser;
use Parse\ParseInstallation;
use Parse\ParseException;
use Parse\ParseAnalytics;
use Parse\ParseFile;
use Parse\ParseCloud;
use Parse\ParseClient;
use Parse\ParsePushStatus;
use Parse\ParseServerInfo;
use Parse\ParseLogs;
use Parse\ParseAudience;

Parse Objects

Parse Objects hold your data, can be saved, queried for, serialized and more! Objects are at the core of this sdk, they allow you to persist your data from php without having to worry about any databasing code.

…

Users

Users are a special kind of object. This class allows individuals to access your applications with their unique information and allows you to identify them distinctly. Users may also be linked with 3rd party accounts such as facebook, twitter, etc.

// Signup
$user = new ParseUser();
$user->setUsername("foo");
$user->setPassword("Q2w#4!o)df");
try {
    $user->signUp();
} catch (ParseException $ex) {
    // error in $ex->getMessage();
}

// Login
try {
    $user = ParseUser::logIn("foo", "Q2w#4!o)df");
} catch(ParseException $ex) {
    // error in $ex->getMessage();
}

// Current user
$user = ParseUser::getCurrentUser();

Session Id and Session Fixation

In an attempt to avoid session fixation exploits, the PHP SDK will call session_regenerate_id() when a session's permissions are elevated (since 1.5.0). In practice this means that session_regenerate_id() will be called when a session goes from no user to anonymous user or from no user / anonymous user to registered user.

Changing the PHP session id should have no impact on the contents of the session and state should be maintained for a user that was anonymous and becomes registered.

Verification Emails

If you are using email verification in your parse server setup you can request to send verification emails by hand.

ParseUser::requestVerificationEmail('[email protected]');

Note that this will only send if the account for the email requested has not already been verified.

ACLs

Access Control Lists (ACLs) allow you to granularly control access to individual Parse Objects. ACLs allow you to configure access to the general public, roles, and individual users themselves.

// Access only by the ParseUser in $user
$userACL = ParseACL::createACLWithUser($user);

// Access only by master key
$restrictedACL = new ParseACL();

// Set individual access rights
$acl = new ParseACL();
$acl->setPublicReadAccess(true);
$acl->setPublicWriteAccess(false);
$acl->setUserWriteAccess($user, true);
$acl->setRoleWriteAccessWithName("PHPFans", true);

Queries

Queries allow you to recall objects that you've saved to parse-server. Query methods and parameters allow allow a varying degree of querying for objects, from all objects of a class to objects created within a particular date range and more.

$query = new ParseQuery("TestObject");

// Get a specific object:
$object = $query->get("anObjectId");

$query->limit(10); // default 100, max 1000

// All results, normally:
$results = $query->find();

// Or pass true to use the master key to override ACLs when querying:
$results = $query->find(true);

// Just the first result:
$first = $query->first();

// Process ALL (without limit) results with "each".
// Will throw if sort, skip, or limit is used.
$query->each(function($obj) {
    echo $obj->getObjectId();
});

Aggregate

Queries can be made using aggregates, allowing you to retrieve objects over a set of inp