feat: Add RBAC permissions API support

[csrbarber]

Summary

• Add HTTP PATCH method support to the request client
• Add Permission resource with fields: id, slug, name, description, resource_type_slug, system, created_at, updated_at
• Add RBAC module with CRUD endpoints for permissions (createPermission, listPermissions, getPermission, updatePermission, deletePermission)

Part 1 of 3 for RBAC support.

Test plan

• 5 new tests covering each permission endpoint
• All existing tests pass

🤖 Generated with Claude Code

[linear]

ENT-4805 workos-php

[greptile-apps]

Greptile Summary

This PR adds Part 1 of RBAC support to the WorkOS PHP SDK, introducing HTTP PATCH support in the curl client, a new Permission resource model, and a new RBAC module with full CRUD endpoints (createPermission, listPermissions, getPermission, updatePermission, deletePermission). The implementation follows existing SDK patterns well, but there are a few issues worth addressing before merge.

Key changes:

• lib/Client.php: Adds METHOD_PATCH constant
• lib/RequestClient/CurlRequestClient.php: Implements PATCH support in the curl switch block, consistent with existing PUT handling
• lib/Resource/Permission.php: New resource class mapping id, slug, name, description, resource_type_slug, system, created_at, updated_at
• lib/RBAC.php: New module with five permission endpoints following the established codebase pattern
• tests/WorkOS/RBACTest.php: Five tests covering each endpoint using the existing mock infrastructure

Issues found:

• The $slug is interpolated directly into URL paths without rawurlencode(). While the standard posts:read slug format is safe, any slug containing a / or ? would misroute the request. All three path-building methods (getPermission, updatePermission, deletePermission) should use rawurlencode($slug).
• updatePermission can be called with no fields to update, resulting in a PATCH request with no body — REST APIs commonly reject this with a 400.
• Public methods lack type hints for $slug, $name, and $limit parameters, inconsistent with optional parameters in the same signatures which do use ?string.
• No PHPDoc documentation on any public method, inconsistent with other modules like Organizations.php.

Confidence Score: 3/5

• Safe to merge for standard slug formats, but the missing URL encoding introduces a real routing bug for edge-case slugs.
• The overall structure is solid and consistent with the existing codebase. The main concern is the missing rawurlencode() on slug path segments — while unlikely with well-formed slugs, it is a genuine bug that would silently misroute requests. The empty PATCH body edge case and missing type hints are lower severity but worth fixing before this API is consumed in production.
• lib/RBAC.php requires the most attention — URL encoding for slug path segments and the empty PATCH body guard.

Important Files Changed

Filename	Overview
lib/RBAC.php	New RBAC module with CRUD endpoints for permissions. Missing URL encoding for slug in path construction (could break routing for slugs with special chars), missing type hints, empty PATCH body not guarded against, and no PHPDoc documentation.
lib/RequestClient/CurlRequestClient.php	Adds PATCH case to the curl switch block, consistent with existing PUT implementation (CURLOPT_CUSTOMREQUEST + CURLOPT_POST). Looks correct and follows the established pattern.
lib/Client.php	Trivial addition of METHOD_PATCH constant. Straightforward and correct.
lib/Resource/Permission.php	New Permission resource class following existing BaseWorkOSResource pattern correctly. RESOURCE_ATTRIBUTES and RESPONSE_TO_RESOURCE_KEY are consistent with each other.
tests/WorkOS/RBACTest.php	Good test coverage for all 5 endpoints using the existing TestHelper and mock pattern. Minor: test fixtures use unencoded slugs in paths (consistent with current implementation, but would need updating if URL encoding is added).

Sequence Diagram

sequenceDiagram
    participant Caller
    participant RBAC
    participant Client
    participant CurlRequestClient
    participant WorkOS_API

    Caller->>RBAC: createPermission(slug, name, description?)
    RBAC->>Client: request(POST, "authorization/permissions", null, params, true)
    Client->>CurlRequestClient: request(post, url, headers, params)
    CurlRequestClient->>WorkOS_API: POST /authorization/permissions (JSON body)
    WorkOS_API-->>CurlRequestClient: 201 Permission JSON
    CurlRequestClient-->>Client: [result, headers, statusCode]
    Client-->>RBAC: response array
    RBAC-->>Caller: Permission resource

    Caller->>RBAC: listPermissions(limit?, before?, after?, order?)
    RBAC->>Client: request(GET, "authorization/permissions", null, params, true)
    Client->>CurlRequestClient: request(get, url?limit=..., headers, params)
    CurlRequestClient->>WorkOS_API: GET /authorization/permissions?limit=...
    WorkOS_API-->>CurlRequestClient: 200 List JSON
    CurlRequestClient-->>Client: [result, headers, statusCode]
    Client-->>RBAC: response array
    RBAC-->>Caller: [before, after, Permission[]]

    Caller->>RBAC: updatePermission(slug, name?, description?)
    RBAC->>Client: request(PATCH, "authorization/permissions/{slug}", null, params, true)
    Client->>CurlRequestClient: request(patch, url, headers, params)
    CurlRequestClient->>WorkOS_API: PATCH /authorization/permissions/{slug} (JSON body)
    WorkOS_API-->>CurlRequestClient: 200 Permission JSON
    CurlRequestClient-->>Client: [result, headers, statusCode]
    Client-->>RBAC: response array
    RBAC-->>Caller: Permission resource

    Caller->>RBAC: deletePermission(slug)
    RBAC->>Client: request(DELETE, "authorization/permissions/{slug}", null, null, true)
    Client->>CurlRequestClient: request(delete, url, headers, null)
    CurlRequestClient->>WorkOS_API: DELETE /authorization/permissions/{slug}
    WorkOS_API-->>CurlRequestClient: 204 No Content
    CurlRequestClient-->>Client: [result, headers, statusCode]
    Client-->>RBAC: response array
    RBAC-->>Caller: []

Loading

_{Last reviewed commit: 51653bc}