jackwh/nylas-v3-api-php

Nylas API v3 PHP SDK client

dev-main 2024-09-15 18:03 UTC

Requires

• php: ^8.1

Requires (Dev)

• pestphp/pest: ^1.21
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^9.5
• roave/security-advisories: dev-latest

MIT

• Nylas Inc.
• Jack Webb-Heller

• php
• JackWH
• nylas
• nylas-v3-api-php

README

PHP API clients for the Nylas V3 API.

This is an experimental package and is not officially endorsed by Nylas. I've released this as their PHP SDK is no longer actively maintained, and the only other PHP clients available are for V2. Please refer to the notes below for how the API clients were generated.

Installation and Usage

Install the project using Composer:

composer require "jackwh/nylas-v3-api-php":"dev-main"

You can then use the relevant API clients like so:

use JackWH\NylasV3;

$accessToken = '**********';
$grantId     = '##########';

$api = new NylasV3\EmailCalendar\Api\CalendarApi(
    new \GuzzleHttp\Client(),
    NylasV3\EmailCalendar\Configuration::getDefaultConfiguration()->setAccessToken($accessToken)
);

$result = $api->getCalendars($grantId, limit: 10);

In this example you'll receive back a NylasV3\EmailCalendar\Model\GetCalendars200Response object, with entries mapped to NylasV3\EmailCalendar\Model\Calendar objects. When converted to JSON the output will look something like this:

{
    "request_id": "17262346...",
    "data": [
        {
            "name": "My Calendar",
            "timezone": "Europe\/London",
            "hex_color": "#0e61b9",
            "hex_foreground_color": "#ffffff",
            "grant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "id": "[e-mail]",
            "object": "calendar",
            "is_primary": false,
            "read_only": false,
            "is_owned_by_user": true
        },
        {
            "description": "Holidays and Observances in United Kingdom",
            "name": "Holidays in United Kingdom",
            "timezone": "Europe\/London",
            "hex_color": "#711a76",
            "hex_foreground_color": "#ffffff",
            "grant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "id": "en.uk#[e-mail]",
            "object": "calendar",
            "is_primary": false,
            "read_only": true,
            "is_owned_by_user": false
        }
    ],
    "next_cursor": "EiIKDAj..."
}

About This Repository

As there's no official v3 API client for PHP, I've done my best to semi-automatically generate this one. There were a few hoops to jump through, I'm sure there must be an easier/simpler way to do this (if anybody knows, please explain!). Here's how I went about it...

1. Export OpenAPI specs from Nylas' documentation for each API, and save to api_specs/yaml.
2. Take the YAML specs and convert them to JSON, place these alongside the originals in api_specs/yaml.
3. Due to a bug in the PHP OpenAPI generator, we need to dereference $ref pointers using the npm script below. This calls the api_specs/utilities/dereference-json.js script, which recursively dereferences all $ref pointers in each JSON OpenAPI spec. The final JSON specs are saved to api_specs:

npm run dereference-json

1. Finally we can generate client code for each of the APIs using the OpenAPI Generator:

openapi-generator generate -g php-nextgen \
  -o src/api/administration/ \
  -i api_specs/administration.json \
  --openapi-normalizer REF_AS_PARENT_IN_ALLOF=true,REFACTOR_ALLOF_WITH_PROPERTIES_ONLY=true,REMOVE_ANYOF_ONEOF_AND_KEEP_PROPERTIES_ONLY=true \
  --invoker-package="JackWH\\NylasV3\\Administration" \
  --additional-properties=composerPackageName="jackwh/nylas-v3-api-php",variableNamingConvention="snake_case"

openapi-generator generate -g php-nextgen \
  -o src/api/email-calendar/ \
  -i api_specs/email-calendar.json \
  --openapi-normalizer REF_AS_PARENT_IN_ALLOF=true,REFACTOR_ALLOF_WITH_PROPERTIES_ONLY=true,REMOVE_ANYOF_ONEOF_AND_KEEP_PROPERTIES_ONLY=true \
  --invoker-package="JackWH\\NylasV3\\EmailCalendar" \
  --additional-properties=composerPackageName="jackwh/nylas-v3-api-php",variableNamingConvention="snake_case"

openapi-generator generate -g php-nextgen \
  -o src/api/scheduler/ \
  -i api_specs/scheduler.json \
  --openapi-normalizer REF_AS_PARENT_IN_ALLOF=true,REFACTOR_ALLOF_WITH_PROPERTIES_ONLY=true,REMOVE_ANYOF_ONEOF_AND_KEEP_PROPERTIES_ONLY=true \
  --invoker-package="JackWH\\NylasV3\\Scheduler" \
  --additional-properties=composerPackageName="jackwh/nylas-v3-api-php",variableNamingConvention="snake_case"

Changes to the OpenAPI spec

Any small changes I've made to the OpenAPI specs since first generating the clients are detailed below:

• email-calendar.yaml:
  • Remove "minItems": *" constraints from Event participants and Draft to arrays, as the generated client was throwing InvalidArgumentExceptions when trying to serialize these objects. (I assume this was an error from the original spec.)