Download the PHP package grantholle/powerschool-api without Composer

PowerSchool API

Taking inspiration from Laravel's database and Eloquent Builder class, this allows you to make api requests against PowerSchool very fluently and naturally. It handles token authentication automatically, so you can just worry about writing the requests and not the boilerplate.

This package is to be used with alongside a PowerSchool plugin that has enabled <oauth/> in the plugin.xml. This guide assumes you have PowerSchool API and plugin knowledge and does not cover the details of a plugin or its API.

Breaking changes for v4

• Requires PHP ^8.1
• Requires Laravel ^10.0

Breaking changes for v3

• Requires PHP ^8.0
• Requests return a new Response instead of stdClass, see below for details

Breaking changes for v2

• SSO functionality has been abstracted to a new package, grantholle/laravel-powerschool-auth
• The namespace is now GrantHolle\PowerSchool\Api

More functionality was added in v2, along with tests for peace of mind.

Installation

The package will be automatically discovered by Laravel, so there's no reason to add it to config/app.php unless you want to.

Configuration

You need to set some variables in .env.

Optionally, you can publish the config file to store the server address, client ID, and secret to interact with PowerSchool. This will generate config/powerschool.php, but is not necessary.

Debugging

You can enable debugging with Ray that will display the raw and transformed responses for each request. This is helpful in viewing the response from PowerSchool and the GrantHolle\PowerSchool\Api\Response object's data. You will need to install the Laravel package and enable debugging:

Commands

API

Using the facade, GrantHolle\PowerSchool\Api\Facades\PowerSchool, you can fluently build a request for PowerSchool. By also providing several aliases to key functions, you can write requests in a way that feels comfortable to you and is easy to read. Below are examples that build on each other. See examples below to put them all together.

setTable(string $table)

Aliases: table(), forTable(), againstTable()

This "sets" the table with which you're interacting. Applies to database extensions.

setId($id)

Aliases: id(), forId()

Sets the id for a get, put, or delete request when interacting with a specific entry in the database.

setMethod(string $method)

Aliases: usingMethod(), get(), post(), put(), patch(), delete()

Sets the HTTP verb for the request. When using the functions get(), post(), put(), patch(), or delete(), the request is sent automatically.

setData(Array $data)

Aliases: withData(), with()

Sets the data that gets sent with requests. If it's for a custom table, you can just send the fields and their values and the structure that is compatible with PowerSchool is build automatically. If it's a named query, it's just the args that have been configured with the query.

setNamedQuery(string $query, Array $data = [])

Aliases: namedQuery(), powerQuery(), pq()

The first parameter is the name of the query, following the required convention set forth by PowerSchool, com.organization.product.area.name. The second is the data that you may need to perform the query which has been configured in the plugin's named query xml file. If the data is included, the request is sent automatically.

setEndpoint(string $query)

Aliases: toEndpoint(), to(), endpoint()

Sets the endpoint for core PS resources.

q(string $expression)

Aliases: queryExpression()

Sets the q variable to the given FIQL expression.

adHocFilter(string $expression)

Aliases: filter()

Sets the $q query variable for adding ad-hoc filtering to PowerQueries.

adHocOrder(string $expression)

Aliases: order()

Sets the order query variable for adding ad-hoc ordering to PowerQueries.

pageSize(int $pageSize)

Sets the pagesize query variable.

page(int $page)

Sets the page query variable for pagination.

sort(string|array $columns, bool $descending = false)

Sets the sort and sortdescending variables.

includeCount()

Includes the count of all the records in the results.

withQueryString(string|array $queryString)

Aliases: query()

This will set the query string en masse rather than using the convenience methods.

projection(string|array $projection)

Sets the projection query variable for the request.

excludeProjection()

Aliases: withoutProjection()

Prevents the projection query variable from being included in the request.

dataVersion(int $version, string $applicationName)

Aliases: withDataVersion()

Sets the $dataversion and $dataversion_applicationname data items.

expansions(string|array $expansions)

Aliases: withExpansions()

Adds the expansions query variable.

extensions(string|array $expansions)

Aliases: withExtensions()

Adds the extensions query variable.

Performing Requests

There are many ways to perform the request after building queries. At the end of the day, each one sets the method/HTTP verb before calling send(). If you'd like to call send(), make sure you set the method by calling method(string $verb). There are also helpers to set methods using constants.

send()

Sends the request using the verb set. By default will return the results from the query. You can also call asJsonResponse() prior to sending to get an instance of Laravel's JsonResponse class which could be returned directly to the client.

count()

Calling count() on the builder will perform a count query by appending /count to the end of the endpoint and perform the get request automatically.

get(string $endpoint = null)

Sets the verb to be get and sends the request. You can also pass the endpoint directly to set the endpoint and perform the request automatically.

post()

Sets the verb to be post and sends the request.

put()

Sets the verb to be put and sends the request.

path()

Sets the verb to be path and sends the request.

delete()

Sets the verb to be delete and sends the request.

getDataSubscriptionChanges(string $applicationName, int $version)

Performs the "delta pull" for a data version subscription.

Pagination

When using PowerQueries, you can easily paginate results using the $builder->paginate($pageSize) function. You can use this inside of a while loop to process all the results in your query more efficiently than returning the full result. The default page size is 100.

Responses

Prior to v3, API requests returned a simple stdClass instance containing the raw response from PowerSchool. Since v3, there's a new GrantHolle\PowerSchool\Api\Response class that gets returned, which implements ArrayAccess. This gives you a more ergonomic way of handling the data that gets returned from PowerSchool. Depending on the request you're making, PowerSchool returns a variety of keys and data nesting. The new Response class attempts to normalize the data that gets returned, making it much simpler for you to process.

Singular responses

Some responses are meant to return a single record, such as a response for /ws/contacts/contact/{id}. For these responses, the properties can be accessed as an associative array.

The @extensions and @expansions fields will be parsed into $extensions and $expansions properties as arrays.

List responses

For the responses that return a listing of results, the Response can be iterated using foreach. You don't need to worry about the property nesting, as the response will be inferred from the type of response.

For get table listings, the results are nested awkwardly. For example,

We can reduce the awkwardness of the results by calling squashTableResponse() on the Response object.

License

MIT

Contributing

Thanks for taking the time to submit an issue or pull request. If it's a new feature, do your best to add a test to cover the functionality. Then run: