grantholle / powerschool-api
A Laravel package to make interacting with PowerSchool less painful.
Installs: 12 869
Dependents: 1
Suggesters: 0
Security: 0
Stars: 13
Watchers: 3
Forks: 1
Open Issues: 0
Requires
- php: ^8.1
- ext-json: *
- guzzlehttp/guzzle: ^7.0.1
- illuminate/console: ^10.0|^11.0
- illuminate/support: ^10.0|^11.0
Requires (Dev)
- orchestra/testbench: ^9.0
- spatie/ray: ^1.30
- dev-main
- 4.4.2
- 4.4.1
- 4.4.0
- 4.3.0
- 4.2.6
- 4.2.5
- 4.2.4
- 4.2.3
- 4.2.2
- 4.2.1
- 4.2.0
- 4.1.0
- 4.0.0
- 3.2.8
- 3.2.7
- 3.2.6
- 3.2.5
- 3.2.4
- 3.2.3
- 3.2.2
- 3.2.1
- 3.2.0
- 3.1.4
- 3.1.3
- 3.1.2
- 3.1.1
- 3.1.0
- 3.0.1
- 3.0.0
- 2.5.0
- 2.4.8
- 2.4.7
- 2.4.6
- 2.4.5
- 2.4.4
- 2.4.3
- 2.4.2
- 2.4.1
- 2.4.0
- 2.3.1
- 2.3.0
- 2.2.0
- 2.1.1
- 2.1.0
- 2.0.1
- 1.4.3
- 1.4.2
- 1.4.0
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.1
- 1.1.1
- 1.1.0
- 1.0.0
This package is auto-updated.
Last update: 2024-10-17 14:23:10 UTC
README
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 ofstdClass
, 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
composer require grantholle/powerschool-api
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
.
POWERSCHOOL_ADDRESS=
POWERSCHOOL_CLIENT_ID=
POWERSCHOOL_CLIENT_SECRET=
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.
php artisan vendor:publish --provider="GrantHolle\PowerSchool\Api\PowerSchoolApiServiceProvider"
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:
# App debug needs to be enabled also
APP_DEBUG=true
POWERSCHOOL_DEBUG=true
Commands
# Fetches authorization token and caches it
php artisan powerschool:auth
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; $request = PowerSchool::table('u_my_custom_table');
setId($id)
Aliases: id(), forId()
Sets the id for a get, put, or delete request when interacting with a specific entry in the database.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; $request = PowerSchool::table('u_my_custom_table')->forId(100);
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; // This request is still not sent $request = PowerSchool::table('u_my_custom_table')->setId(100)->method('get'); // This request is set to the get method and sent automatically $response = PowerSchool::table('u_my_custom_table')->id(100)->get(); $response = PowerSchool::table('u_my_custom_table')->id(100)->get(); $response = PowerSchool::table('u_my_custom_table')->id(100)->delete(); // The above example could be rewritten like this... $response = PowerSchool::table('u_my_custom_table')->id(100)->setMethod('get')->send();
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; $data = [ 'column_one' => 'value', 'column_two' => 'value', ]; // Doing "table" requests, this not getting sent $request = PowerSchool::table('u_my_custom_table')->with($data)->method('post'); // A PowerQuery (see below) $response = PowerSchool::pq('com.organization.product.area.name')->withData($data);
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; // Will not get sent $request = PowerSchool::powerQuery('com.organization.product.area.name'); // Gets posted automatically $response = PowerSchool::powerQuery('com.organization.product.area.name', ['schoolid' => '100']);
setEndpoint(string $query)
Aliases: toEndpoint(), to(), endpoint()
Sets the endpoint for core PS resources.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; $requestData = [ 'students' => [ 'student' => [ 'client_uid' => 100, 'action' => 'INSERT', 'local_id' => 100, 'name' => [ 'first_name' => 'John', 'last_name' => 'Doe', ], 'demographics' => [ 'gender' => 'M', 'birth_date' => '2002-08-01', ], 'school_enrollment' => [ 'entry_date' => now()->format('Y-m-d'), 'exit_date' => now()->subDays(1)->format('Y-m-d'), 'grade_level' => 10, 'school_number' => 100, ], ], ], ]; $response = PowerSchool::toEndpoint('/ws/v1/student')->with($requestData)->post();
q(string $expression)
Aliases: queryExpression()
Sets the q
variable to the given FIQL expression.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; PowerSchool::endpoint('/ws/v1/school/3/student') ->q('name.last_name==Ada*') ->get();
adHocFilter(string $expression)
Aliases: filter()
Sets the $q
query variable for adding ad-hoc filtering to PowerQueries.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; PowerSchool::pq('com.organization.plugin_name.entity.query_name') ->filter('number_column=lt=100') ->post();
adHocOrder(string $expression)
Aliases: order()
Sets the order
query variable for adding ad-hoc ordering to PowerQueries.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; PowerSchool::pq('com.organization.plugin_name.entity.query_name') ->order('students.last_name,students.first_name,students.entrydate;desc') ->post();
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; PowerSchool::pq('com.organization.plugin_name.entity.query_name') ->sort('column1'); // ?sort=column1&sortdescending=false
includeCount()
Includes the count of all the records in the results.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; PowerSchool::pq('com.pearson.core.guardian.student_guardian_detail') ->includeCount() ->post(); // { // "name":"Students", // "count":707625, // "record":[ // { // "id":3328, // "name":"Students", // ... // }, // ... Only first page of actual results returned // ], // "@extensions":"activities,u_dentistry,studentcorefields,c_studentlocator" // }
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.
use GrantHolle\PowerSchool\Api\RequestBuilder; RequestBuilder::GET; RequestBuilder::POST; RequestBuilder::PUT; RequestBuilder::PATCH; RequestBuilder::DELETE;
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; PowerSchool::get('/ws/v1/staff/111');
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; PowerSchool::getDataSubscriptionChanges('myapp', 12345); // { // "$dataversion": "16323283", // "tables": { // "userscorefields": [ // 802 // ], // "users": [ // 851, // 769, // 802, // 112 // ] // } // }
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.
use GrantHolle\PowerSchool\Api\Facades\PowerSchool; // PowerQuery // You have to set data in a separate function call // Otherwise the request will be sent automatically $builder = PowerSchool::pq('com.organization.plugin_name.entity.query_name') ->with(['some_variable' => $value]); // "Normal" endpoint $builder = PowerSchool::to('/ws/v1/school/1/course') ->method(PowerSchool::GET); // "Table" endpoints $builder = PowerSchool::table('u_my_table') ->method(PowerSchool::GET); while ($records = $builder->paginate(25)) { // Do something awesome }
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.
$response = PowerSchool::to('/ws/contacts/contact/123') ->get(); // Since Response implements ArrayAccess, we can access the attributes with keys $response['contactId']; // 123
The @extensions
and @expansions
fields will be parsed into $extensions
and $expansions
properties as arrays.
$response->extensions; // [ // "personcorefields", // ]
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.
$results = PowerSchool::to('/ws/v1/district/school') ->get(); foreach ($results as $result) { // $result will be an array representing the school object returned }
For get
table listings, the results are nested awkwardly. For example,
PowerSchool::table('u_my_table')->get(); // This returns results like [ [ 'id' => 1, 'tables' => [ 'u_my_table' => [ 'column' => '', 'column' => '', // etc ] ] ], // and on and on ]
We can reduce the awkwardness of the results by calling squashTableResponse()
on the Response
object.
PowerSchool::table('u_my_table') ->get() ->squashTableResponse(); // Now the results will be simpler [ [ 'column' => '', 'column' => '', // etc ], // and on and on ]
License
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:
./vendor/bin/phpunit