Skip to content

Commit 0c57b35

Browse files
bradenkeithericrobertsmattgdpepeloper
authored
IDE & Typehint improvements (#264)
* Improve Webhook and BaseWorkOSResource PHPDoc types * Enhance Webhook class with improved code style and PHPDoc annotations * Add accessToken and refreshToken to AuthenticationResponse class * Update AuthenticationResponse class to include organizationId as nullable, and add accessToken, refreshToken, and impersonator properties * Enhance OrganizationMembership class with additional PHPDoc properties for improved type documentation * Add metadata and external id (#268) And allow to be passed when creating or updating a user or organization. * Add email standard attribute to DirectoryUser and mark deprecated standard attributes (#261) * Add function to get organization by external id (#270) And fix typo in getOrganization docstring * Add support for creating, getting and updating users with external_id property (#267) Co-authored-by: Eric Roberts <ericroberts@gmail.com> * Bump to version 4.22.0. (#269) * Structured responses to webhook events (#265) * Add WebhookResponse class for handling webhook actions and responses * Refactor WebhookResponse create method and improve validation * Resolve linting error --------- Co-authored-by: Braden Keith <bkeith@romegadigital.com> * Update deprecation notices in DirectoryUser class to include version information and improve clarity * Update deprecation notices in Organizations class to include version information and improve formatting * Update doc blocks for deprecation notices * Update tests to expect Role Slug --------- Co-authored-by: Braden Keith <bkeith@romegadigital.com> Co-authored-by: Eric Roberts <ericroberts@gmail.com> Co-authored-by: Matt Dzwonczyk <9063128+mattgd@users.noreply.github.com> Co-authored-by: Pepe <pgarciag93@gmail.com>
1 parent bd3e4fb commit 0c57b35

File tree

12 files changed

+178
-75
lines changed

12 files changed

+178
-75
lines changed

‎lib/AuditLogs.php‎

Lines changed: 28 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -10,36 +10,35 @@
1010
class AuditLogs
1111
{
1212
/**
13+
* Creates an audit log event for an organization.
1314
*
14-
* @param string $organizationId the unique identifier for the organization.
15-
* @param array $event Associative array containing the keys detailed below
16-
* string "action" Specific activity performed by the actor. REQUIRED.
17-
* string "occurred_at" ISO-8601 datetime at which the event happened. REQUIRED.
18-
* array "actor" Associative array describing Actor of the event. REQUIRED.
19-
* KEYS:
20-
* string "id" - REQUIRED
21-
* string "name" - NOT REQUIRED
22-
* string "type" - REQUIRED
23-
* array "metadata" - Associative array ["Any Key" => "Any Value] - NOT REQUIRED
24-
* array "targets" Targets of the event. Nested array as there can be multiple targets. REQUIRED
25-
* KEYS:
26-
* string "id" - REQUIRED
27-
* string "name" - NOT REQUIRED
28-
* string "type" - REQUIRED
29-
* array "metadata" - Associative array ["Any Key" => "Any Value] - NOT REQUIRED
30-
* array "context" Context of the event. REQUIRED.
31-
* KEYS:
32-
* string "location" - REQUIRED
33-
* string "user_agent" - NOT REQUIRED
34-
* int "version" Version of the event. Required if version is anything other than 1. NOT REQUIRED.
35-
* array "metadata" Arbitrary key-value data containing information associated with the event. NOT REQUIRED
36-
* @param string $idempotencyKey Unique key guaranteeing idempotency of events for 24 hours.
15+
* @param string $organizationId The unique identifier for the organization.
16+
* @param array $event An associative array with the following keys:
17+
* - **action** (string, *required*): Specific activity performed by the actor.
18+
* - **occurred_at** (string, *required*): ISO-8601 datetime when the event occurred.
19+
* - **actor** (array, *required*): Associative array describing the actor.
20+
* - **id** (string, *required*): Unique identifier for the actor.
21+
* - **name** (string, *optional*): Name of the actor.
22+
* - **type** (string, *required*): Type or role of the actor.
23+
* - **metadata** (array, *optional*): Arbitrary key-value data.
24+
* - **targets** (array, *required*): Array of associative arrays for each target.
25+
* Each target includes:
26+
* - **id** (string, *required*): Unique identifier for the target.
27+
* - **name** (string, *optional*): Name of the target.
28+
* - **type** (string, *required*): Type or category of the target.
29+
* - **metadata** (array, *optional*): Arbitrary key-value data.
30+
* - **context** (array, *required*): Associative array providing additional context.
31+
* - **location** (string, *required*): Location associated with the event.
32+
* - **user_agent** (string, *optional*): User agent string if applicable.
33+
* - **version** (int, *optional*): Event version. Required if the version is not 1.
34+
* - **metadata** (array, *optional*): Additional arbitrary key-value data for the event.
35+
*
36+
* @param string $idempotencyKey A unique key ensuring idempotency of events for 24 hours.
3737
*
3838
* @throws Exception\WorkOSException
3939
*
40-
* @return Resource\AuditLogCreateEventStatus
40+
* @return Resource\AuditLogCreateEventStatus
4141
*/
42-
4342
public function createEvent($organizationId, $event, $idempotencyKey = null)
4443
{
4544
$eventsPath = "audit_logs/events";
@@ -64,7 +63,7 @@ public function createEvent($organizationId, $event, $idempotencyKey = null)
6463
* @var null|string $rangeStart ISO-8601 Timestamp of the start of Export's the date range.
6564
* @var null|string $rangeEnd ISO-8601 Timestamp of the end of Export's the date range.
6665
* @var null|array $actions Actions that Audit Log Events will be filtered by.
67-
* @var null|array $actors Actor names that Audit Log Events will be filtered by.
66+
* @var null|array $actors Actor names that Audit Log Events will be filtered by. @deprecated 3.3.0 Use $actorNames instead. This method will be removed in a future major version.
6867
* @var null|array $targets Target types that Audit Log Events will be filtered by.
6968
* @var null|array $actorNames Actor names that Audit Log Events will be filtered by.
7069
* @var null|array $actorIds Actor IDs that Audit Log Events will be filtered by.
@@ -79,9 +78,9 @@ public function createExport($organizationId, $rangeStart, $rangeEnd, $actions =
7978
$createExportPath = "audit_logs/exports";
8079

8180
$params = [
82-
"organization_id" => $organizationId,
83-
"range_end" => $rangeEnd,
84-
"range_start" => $rangeStart
81+
"organization_id" => $organizationId,
82+
"range_end" => $rangeEnd,
83+
"range_start" => $rangeStart
8584
];
8685

8786
if (!is_null($actions)) {

‎lib/MFA.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,11 +108,12 @@ public function challengeFactor(
108108

109109

110110
/**
111+
* @deprecated 1.12.0 Use `verifyChallenge` instead. This method will be removed in a future major version.
111112
* Verifies the one time password provided by the end-user.
112113
*
113114
* @param string $authenticationChallengeId - The ID of the authentication challenge that provided the user the verification code.
114115
* @param string $code - The verification code sent to and provided by the end user.
115-
*/
116+
*/
116117

117118
public function verifyFactor(
118119
$authenticationChallengeId,

‎lib/Organizations.php‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,11 @@ public function listOrganizations(
3434
) {
3535
$organizationsPath = "organizations";
3636
$params = [
37-
"limit" => $limit,
38-
"before" => $before,
39-
"after" => $after,
40-
"domains" => $domains,
41-
"order" => $order
37+
"limit" => $limit,
38+
"before" => $before,
39+
"after" => $after,
40+
"domains" => $domains,
41+
"order" => $order
4242
];
4343

4444
$response = Client::request(
@@ -62,9 +62,9 @@ public function listOrganizations(
6262
* Create Organization.
6363
*
6464
* @param string $name The name of the Organization.
65-
* @param null|array $domains [Deprecated] The domains of the Organization. Use domain_data instead.
65+
* @param null|array $domains @deprecated 4.5.0 The domains of the Organization. Use domain_data instead.
6666
* @param null|array $domain_data The domains of the Organization.
67-
* @param null|boolean $allowProfilesOutsideOrganization [Deprecated] If you need to allow sign-ins from
67+
* @param null|boolean $allowProfilesOutsideOrganization @deprecated 4.5.0 If you need to allow sign-ins from
6868
* any email domain, contact support@workos.com.
6969
* @param null|string $idempotencyKey is a unique string that identifies a distinct organization
7070
* @param null|string $externalId The organization's external id
@@ -86,7 +86,7 @@ public function createOrganization(
8686
$idempotencyKey ? $headers = array("Idempotency-Key: $idempotencyKey") : $headers = null;
8787
$organizationsPath = "organizations";
8888

89-
$params = [ "name" => $name ];
89+
$params = ["name" => $name];
9090

9191
if (isset($domains)) {
9292
$params["domains"] = $domains;
@@ -113,10 +113,10 @@ public function createOrganization(
113113
* Update Organization.
114114
*
115115
* @param string $organization An Organization identifier.
116-
* @param null|array $domains [Deprecated] The domains of the Organization. Use domain_data instead.
116+
* @param null|array $domains @deprecated 4.5.0 The domains of the Organization. Use domain_data instead.
117117
* @param null|array $domain_data The domains of the Organization.
118118
* @param null|string $name The name of the Organization.
119-
* @param null|boolean $allowProfilesOutsideOrganization [Deprecated] If you need to allow sign-ins from
119+
* @param null|boolean $allowProfilesOutsideOrganization @deprecated 4.5.0 If you need to allow sign-ins from
120120
* any email domain, contact support@workos.com.
121121
* @param null|string $stripeCustomerId The Stripe Customer ID of the Organization.
122122
* @param null|string $externalId The organization's external id
@@ -136,7 +136,7 @@ public function updateOrganization(
136136
) {
137137
$organizationsPath = "organizations/{$organization}";
138138

139-
$params = [ "name" => $name ];
139+
$params = ["name" => $name];
140140

141141
if (isset($domains)) {
142142
$params["domains"] = $domains;

‎lib/Resource/AuthenticationResponse.php‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,25 @@
66
* Class AuthenticationResponse.
77
*
88
* @property User $user
9-
* @property string $organizationId
9+
* @property ?string $organizationId
10+
* @property string $accessToken
11+
* @property string $refreshToken
12+
* @property ?Impersonator $impersonator
1013
*/
1114
class AuthenticationResponse extends BaseWorkOSResource
1215
{
1316
public const RESOURCE_ATTRIBUTES = [
1417
"user",
1518
"organizationId",
1619
"impersonator",
20+
"accessToken",
21+
"refreshToken",
1722
];
1823

1924
public const RESPONSE_TO_RESOURCE_KEY = [
2025
"organization_id" => "organizationId",
26+
"access_token" => "accessToken",
27+
"refresh_token" => "refreshToken",
2128
];
2229

2330
public static function constructFromResponse($response)

‎lib/Resource/BaseWorkOSResource.php‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,22 @@
44

55
class BaseWorkOSResource
66
{
7+
/**
8+
* Maps response keys to resource keys.
9+
* Child classes should override this constant.
10+
*
11+
* @var array<string, string>
12+
*/
13+
protected const RESPONSE_TO_RESOURCE_KEY = [];
14+
15+
/**
16+
* List of attributes available in this resource.
17+
* Child classes should override this constant.
18+
*
19+
* @var array<string>
20+
*/
21+
protected const RESOURCE_ATTRIBUTES = [];
22+
723
/**
824
* @var array $values;
925
*/

‎lib/Resource/DirectoryUser.php‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,20 +16,20 @@ class DirectoryUser extends BaseWorkOSResource
1616
"firstName",
1717
"email",
1818
/**
19-
* [Deprecated] Will be removed in a future major version.
19+
* @deprecated 4.22.0 Will be removed in a future major version.
2020
* Enable the `emails` custom attribute in dashboard and pull from customAttributes instead.
2121
* See https://workos.com/docs/directory-sync/attributes/custom-attributes/auto-mapped-attributes for details.
2222
*/
2323
"emails",
2424
/**
25-
* [Deprecated] Will be removed in a future major version.
25+
* @deprecated 4.22.0 Will be removed in a future major version.
2626
* Enable the `username` custom attribute in dashboard and pull from customAttributes instead.
2727
* See https://workos.com/docs/directory-sync/attributes/custom-attributes/auto-mapped-attributes for details.
2828
*/
2929
"username",
3030
"lastName",
3131
/**
32-
* [Deprecated] Will be removed in a future major version.
32+
* @deprecated 4.22.0 Will be removed in a future major version.
3333
* Enable the `job_title` custom attribute in dashboard and pull from customAttributes instead.
3434
* See https://workos.com/docs/directory-sync/attributes/custom-attributes/auto-mapped-attributes for details.
3535
*/
@@ -59,7 +59,9 @@ class DirectoryUser extends BaseWorkOSResource
5959
];
6060

6161
/**
62-
* [Deprecated] Use `email` instead.
62+
* @deprecated 4.22.0 Use `email` property instead.
63+
*
64+
* @return string|null The primary email address if found, null otherwise
6365
*/
6466
public function primaryEmail()
6567
{

‎lib/Resource/OrganizationMembership.php‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,16 @@
44

55
/**
66
* Class OrganizationMembership.
7+
*
8+
* @property 'organization_membership' $object
9+
* @property string $id
10+
* @property string $userId
11+
* @property string $organizationId
12+
* @property RoleResponse $role
13+
* @property 'active'|'inactive'|'pending' $status
14+
* @property string $createdAt
15+
* @property string $updatedAt
716
*/
8-
917
class OrganizationMembership extends BaseWorkOSResource
1018
{
1119
public const RESOURCE_TYPE = "organization_membership";
@@ -15,6 +23,7 @@ class OrganizationMembership extends BaseWorkOSResource
1523
"id",
1624
"userId",
1725
"organizationId",
26+
"role",
1827
"status",
1928
"createdAt",
2029
"updatedAt"
@@ -25,6 +34,7 @@ class OrganizationMembership extends BaseWorkOSResource
2534
"id" => "id",
2635
"user_id" => "userId",
2736
"organization_id" => "organizationId",
37+
"role" => "role",
2838
"status" => "status",
2939
"created_at" => "createdAt",
3040
"updated_at" => "updatedAt"

‎lib/Resource/Webhook.php‎

Lines changed: 62 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,74 @@
66
* Class Webhook.
77
*
88
* Representation of a webhook resulting from a client ConstructEvent function.
9+
*
10+
* @property-read 'user_registration_action_context'|'authentication_action_context' $object The type of webhook event
11+
*
12+
* User Registration Action Properties
13+
* @property-read ?object{
14+
* object: 'user_data',
15+
* email: string,
16+
* first_name: string,
17+
* last_name: string
18+
* } $user_data User information for registration events
19+
* @property-read ?object{
20+
* object: 'invitation',
21+
* id: string,
22+
* email: string,
23+
* expires_at: string,
24+
* created_at: string,
25+
* updated_at: string,
26+
* accepted_at: ?string,
27+
* revoked_at: ?string,
28+
* organization_id: string,
29+
* inviter_user_id: string
30+
* } $invitation Invitation details for registration events
31+
*
32+
* Authentication Action Properties
33+
* @property-read ?object{
34+
* object: 'user',
35+
* id: string,
36+
* email: string,
37+
* first_name: string,
38+
* last_name: string,
39+
* email_verified: bool,
40+
* profile_picture_url: string,
41+
* created_at: string,
42+
* updated_at: string
43+
* } $user User information for authentication events
44+
* @property-read ?string $issuer The authentication issuer
45+
* @property-read ?object{
46+
* object: 'organization',
47+
* id: string,
48+
* name: string,
49+
* allow_profiles_outside_organization: bool,
50+
* domains: array<string>,
51+
* created_at: string,
52+
* updated_at: string
53+
* } $organization Organization details for authentication events
54+
* @property-read ?object{
55+
* object: 'organization_membership',
56+
* id: string,
57+
* user_id: string,
58+
* organization_id: string,
59+
* role: array{slug: string},
60+
* status: string,
61+
* created_at: string,
62+
* updated_at: string
63+
* } $organization_membership Organization membership details for authentication events
64+
*
65+
* Common Properties
66+
* @property-read string $ip_address IP address of the event
67+
* @property-read string $user_agent User agent string of the event
68+
* @property-read string $device_fingerprint Device fingerprint of the event
969
*/
1070
class Webhook
1171
{
1272
/**
1373
* Creates a webhook object from a payload.
1474
*
15-
* @param $payload
16-
*
17-
* @return Webhook
75+
* @param string $payload JSON string containing webhook data
76+
* @return static
1877
*/
1978
public static function constructFromPayload($payload)
2079
{

‎lib/SSO.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ class SSO
1313
/**
1414
* Generates an OAuth 2.0 authorization URL used to initiate the SSO flow with WorkOS.
1515
*
16-
* @param null|string $domain Domain of the user that will be going through SSO
16+
* @param null|string $domain Domain of the user that will be going through SSO @deprecated 1.5.0 Use $connection or $organization instead.
1717
* @param null|string $redirectUri URI to direct the user to upon successful completion of SSO
1818
* @param null|array $state Associative array containing state that will be returned from WorkOS as a json encoded string
1919
* @param null|string $provider Service provider that handles the identity of the user

‎lib/UserManagement.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1096,6 +1096,7 @@ public function createPasswordReset(
10961096
}
10971097

10981098
/**
1099+
* @deprecated 4.9.0 Use `createPasswordReset` instead. This method will be removed in a future major version.
10991100
* Create Password Reset Email.
11001101
*
11011102
* @param string $email The email of the user that wishes to reset their password.
@@ -1204,6 +1205,7 @@ public function createMagicAuth(
12041205
}
12051206

12061207
/**
1208+
* @deprecated 4.6.0 Use `createMagicAuth` instead. This method will be removed in a future major version.
12071209
* Creates a one-time Magic Auth code and emails it to the user.
12081210
*
12091211
* @param string $email The email address the one-time code will be sent to.

0 commit comments

Comments
 (0)