IDE & Typehint improvements

lib/AuditLogs.php

@@ -10,36 +10,35 @@
 class AuditLogs
 {
     /**
+     * Creates an audit log event for an organization.
      *
-     * @param string $organizationId the unique identifier for the organization.
-     * @param array $event Associative array containing the keys detailed below
-            * string "action" Specific activity performed by the actor. REQUIRED.
-            * string "occurred_at" ISO-8601 datetime at which the event happened. REQUIRED.
-            * array "actor" Associative array describing Actor of the event. REQUIRED.
-                * KEYS:
-                * string "id" - REQUIRED
-                * string "name" - NOT REQUIRED
-                * string "type" - REQUIRED
-                * array "metadata" - Associative array ["Any Key" => "Any Value] - NOT REQUIRED
-            * array "targets" Targets of the event. Nested array as there can be multiple targets. REQUIRED
-                * KEYS:
-                * string "id" - REQUIRED
-                * string "name" - NOT REQUIRED
-                * string "type" - REQUIRED
-                * array "metadata" - Associative array ["Any Key" => "Any Value] - NOT REQUIRED
-            * array "context" Context of the event. REQUIRED.
-                * KEYS:
-                * string "location" -  REQUIRED
-                * string "user_agent" -  NOT REQUIRED
-            * int "version" Version of the event. Required if version is anything other than 1. NOT REQUIRED.
-            * array "metadata" Arbitrary key-value data containing information associated with the event. NOT REQUIRED
-     * @param string $idempotencyKey Unique key guaranteeing idempotency of events for 24 hours.
+     * @param string $organizationId The unique identifier for the organization.
+     * @param array  $event          An associative array with the following keys:
+     *   - **action** (string, *required*): Specific activity performed by the actor.
+     *   - **occurred_at** (string, *required*): ISO-8601 datetime when the event occurred.
+     *   - **actor** (array, *required*): Associative array describing the actor.
+     *     - **id** (string, *required*): Unique identifier for the actor.
+     *     - **name** (string, *optional*): Name of the actor.
+     *     - **type** (string, *required*): Type or role of the actor.
+     *     - **metadata** (array, *optional*): Arbitrary key-value data.
+     *   - **targets** (array, *required*): Array of associative arrays for each target.
+     *     Each target includes:
+     *     - **id** (string, *required*): Unique identifier for the target.
+     *     - **name** (string, *optional*): Name of the target.
+     *     - **type** (string, *required*): Type or category of the target.
+     *     - **metadata** (array, *optional*): Arbitrary key-value data.
+     *   - **context** (array, *required*): Associative array providing additional context.
+     *     - **location** (string, *required*): Location associated with the event.
+     *     - **user_agent** (string, *optional*): User agent string if applicable.
+     *   - **version** (int, *optional*): Event version. Required if the version is not 1.
+     *   - **metadata** (array, *optional*): Additional arbitrary key-value data for the event.
+     *
+     * @param string $idempotencyKey A unique key ensuring idempotency of events for 24 hours.
      *
      * @throws Exception\WorkOSException
      *
-     * @return  Resource\AuditLogCreateEventStatus
+     * @return Resource\AuditLogCreateEventStatus
      */
-
     public function createEvent($organizationId, $event, $idempotencyKey = null)
     {
         $eventsPath = "audit_logs/events";
@@ -64,7 +63,7 @@ public function createEvent($organizationId, $event, $idempotencyKey = null)
      * @var null|string $rangeStart ISO-8601 Timestamp of the start of Export's the date range.
      * @var null|string $rangeEnd ISO-8601 Timestamp  of the end of Export's the date range.
      * @var null|array $actions Actions that Audit Log Events will be filtered by.
-     * @var null|array $actors Actor names that Audit Log Events will be filtered by.
+     * @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.
      * @var null|array $targets Target types that Audit Log Events will be filtered by.
      * @var null|array $actorNames Actor names that Audit Log Events will be filtered by.
      * @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 =
         $createExportPath = "audit_logs/exports";
 
         $params = [
-         "organization_id" => $organizationId,
-         "range_end" => $rangeEnd,
-         "range_start" => $rangeStart
+            "organization_id" => $organizationId,
+            "range_end" => $rangeEnd,
+            "range_start" => $rangeStart
         ];
 
         if (!is_null($actions)) {

lib/MFA.php

@@ -108,11 +108,12 @@ public function challengeFactor(
 
 
     /**
+     * @deprecated 1.12.0 Use `verifyChallenge` instead. This method will be removed in a future major version.
      * Verifies the one time password provided by the end-user.
      *
      * @param string $authenticationChallengeId - The ID of the authentication challenge that provided the user the verification code.
      * @param string $code - The verification code sent to and provided by the end user.
-    */
+     */
 
     public function verifyFactor(
         $authenticationChallengeId,

lib/Organizations.php

@@ -34,11 +34,11 @@ public function listOrganizations(
     ) {
         $organizationsPath = "organizations";
         $params = [
-          "limit" => $limit,
-          "before" => $before,
-          "after" => $after,
-          "domains" => $domains,
-          "order" => $order
+            "limit" => $limit,
+            "before" => $before,
+            "after" => $after,
+            "domains" => $domains,
+            "order" => $order
         ];
 
         $response = Client::request(
@@ -62,9 +62,9 @@ public function listOrganizations(
      * Create Organization.
      *
      * @param string $name The name of the Organization.
-     * @param null|array $domains [Deprecated] The domains of the Organization. Use domain_data instead.
+     * @param null|array $domains @deprecated 4.5.0 The domains of the Organization. Use domain_data instead.
      * @param null|array $domain_data The domains of the Organization.
-     * @param null|boolean $allowProfilesOutsideOrganization [Deprecated] If you need to allow sign-ins from
+     * @param null|boolean $allowProfilesOutsideOrganization @deprecated 4.5.0 If you need to allow sign-ins from
      *      any email domain, contact support@workos.com.
      * @param null|string $idempotencyKey is a unique string that identifies a distinct organization
      * @param null|string $externalId The organization's external id
@@ -86,7 +86,7 @@ public function createOrganization(
         $idempotencyKey ? $headers = array("Idempotency-Key: $idempotencyKey") : $headers = null;
         $organizationsPath = "organizations";
 
-        $params = [ "name" => $name ];
+        $params = ["name" => $name];
 
         if (isset($domains)) {
             $params["domains"] = $domains;
@@ -113,10 +113,10 @@ public function createOrganization(
      * Update Organization.
      *
      * @param string $organization An Organization identifier.
-     * @param null|array $domains [Deprecated] The domains of the Organization. Use domain_data instead.
+     * @param null|array $domains @deprecated 4.5.0 The domains of the Organization. Use domain_data instead.
      * @param null|array $domain_data The domains of the Organization.
      * @param null|string $name The name of the Organization.
-     * @param null|boolean $allowProfilesOutsideOrganization [Deprecated] If you need to allow sign-ins from
+     * @param null|boolean $allowProfilesOutsideOrganization @deprecated 4.5.0 If you need to allow sign-ins from
      *      any email domain, contact support@workos.com.
      * @param null|string $stripeCustomerId The Stripe Customer ID of the Organization.
      * @param null|string $externalId The organization's external id
@@ -136,7 +136,7 @@ public function updateOrganization(
     ) {
         $organizationsPath = "organizations/{$organization}";
 
-        $params = [ "name" => $name ];
+        $params = ["name" => $name];
 
         if (isset($domains)) {
             $params["domains"] = $domains;

lib/Resource/AuthenticationResponse.php

@@ -6,18 +6,25 @@
  * Class AuthenticationResponse.
  *
  * @property User $user
- * @property string $organizationId
+ * @property ?string $organizationId
+ * @property string $accessToken
+ * @property string $refreshToken
+ * @property ?Impersonator $impersonator
  */
 class AuthenticationResponse extends BaseWorkOSResource
 {
     public const RESOURCE_ATTRIBUTES = [
         "user",
         "organizationId",
         "impersonator",
+        "accessToken",
+        "refreshToken",
     ];
 
     public const RESPONSE_TO_RESOURCE_KEY = [
         "organization_id" => "organizationId",
+        "access_token" => "accessToken",
+        "refresh_token" => "refreshToken",
     ];
 
     public static function constructFromResponse($response)

lib/Resource/BaseWorkOSResource.php

@@ -4,6 +4,22 @@
 
 class BaseWorkOSResource
 {
+    /**
+     * Maps response keys to resource keys.
+     * Child classes should override this constant.
+     *
+     * @var array<string, string>
+     */
+    protected const RESPONSE_TO_RESOURCE_KEY = [];
+
+    /**
+     * List of attributes available in this resource.
+     * Child classes should override this constant.
+     *
+     * @var array<string>
+     */
+    protected const RESOURCE_ATTRIBUTES = [];
+
     /**
      * @var array $values;
      */

lib/Resource/DirectoryUser.php

@@ -16,20 +16,20 @@ class DirectoryUser extends BaseWorkOSResource
         "firstName",
         "email",
         /**
-         * [Deprecated] Will be removed in a future major version.
+         * @deprecated 4.22.0 Will be removed in a future major version.
          * Enable the `emails` custom attribute in dashboard and pull from customAttributes instead.
          * See https://workos.com/docs/directory-sync/attributes/custom-attributes/auto-mapped-attributes for details.
          */
         "emails",
         /**
-         * [Deprecated] Will be removed in a future major version.
+         * @deprecated 4.22.0 Will be removed in a future major version.
          * Enable the `username` custom attribute in dashboard and pull from customAttributes instead.
          * See https://workos.com/docs/directory-sync/attributes/custom-attributes/auto-mapped-attributes for details.
          */
         "username",
         "lastName",
         /**
-         * [Deprecated] Will be removed in a future major version.
+         * @deprecated 4.22.0 Will be removed in a future major version.
          * Enable the `job_title` custom attribute in dashboard and pull from customAttributes instead.
          * See https://workos.com/docs/directory-sync/attributes/custom-attributes/auto-mapped-attributes for details.
          */
@@ -59,7 +59,9 @@ class DirectoryUser extends BaseWorkOSResource
     ];
 
     /**
-     * [Deprecated] Use `email` instead.
+     * @deprecated 4.22.0 Use `email` property instead.
+     *
+     * @return string|null The primary email address if found, null otherwise
      */
     public function primaryEmail()
     {

lib/Resource/OrganizationMembership.php

@@ -4,8 +4,16 @@
 
 /**
  * Class OrganizationMembership.
+ *
+ * @property 'organization_membership' $object
+ * @property string $id
+ * @property string $userId
+ * @property string $organizationId
+ * @property RoleResponse $role
+ * @property 'active'|'inactive'|'pending' $status
+ * @property string $createdAt
+ * @property string $updatedAt
  */
-
 class OrganizationMembership extends BaseWorkOSResource
 {
     public const RESOURCE_TYPE = "organization_membership";
@@ -15,6 +23,7 @@ class OrganizationMembership extends BaseWorkOSResource
         "id",
         "userId",
         "organizationId",
+        "role",
         "status",
         "createdAt",
         "updatedAt"
@@ -25,6 +34,7 @@ class OrganizationMembership extends BaseWorkOSResource
         "id" => "id",
         "user_id" => "userId",
         "organization_id" => "organizationId",
+        "role" => "role",
         "status" => "status",
         "created_at" => "createdAt",
         "updated_at" => "updatedAt"

lib/Resource/Webhook.php

@@ -6,15 +6,74 @@
  * Class Webhook.
  *
  * Representation of a webhook resulting from a client ConstructEvent function.
+ *
+ * @property-read 'user_registration_action_context'|'authentication_action_context' $object The type of webhook event
+ *
+ * User Registration Action Properties
+ * @property-read ?object{
+ *     object: 'user_data',
+ *     email: string,
+ *     first_name: string,
+ *     last_name: string
+ * } $user_data User information for registration events
+ * @property-read ?object{
+ *     object: 'invitation',
+ *     id: string,
+ *     email: string,
+ *     expires_at: string,
+ *     created_at: string,
+ *     updated_at: string,
+ *     accepted_at: ?string,
+ *     revoked_at: ?string,
+ *     organization_id: string,
+ *     inviter_user_id: string
+ * } $invitation Invitation details for registration events
+ *
+ * Authentication Action Properties
+ * @property-read ?object{
+ *     object: 'user',
+ *     id: string,
+ *     email: string,
+ *     first_name: string,
+ *     last_name: string,
+ *     email_verified: bool,
+ *     profile_picture_url: string,
+ *     created_at: string,
+ *     updated_at: string
+ * } $user User information for authentication events
+ * @property-read ?string $issuer The authentication issuer
+ * @property-read ?object{
+ *     object: 'organization',
+ *     id: string,
+ *     name: string,
+ *     allow_profiles_outside_organization: bool,
+ *     domains: array<string>,
+ *     created_at: string,
+ *     updated_at: string
+ * } $organization Organization details for authentication events
+ * @property-read ?object{
+ *     object: 'organization_membership',
+ *     id: string,
+ *     user_id: string,
+ *     organization_id: string,
+ *     role: array{slug: string},
+ *     status: string,
+ *     created_at: string,
+ *     updated_at: string
+ * } $organization_membership Organization membership details for authentication events
+ *
+ * Common Properties
+ * @property-read string $ip_address IP address of the event
+ * @property-read string $user_agent User agent string of the event
+ * @property-read string $device_fingerprint Device fingerprint of the event
  */
 class Webhook
 {
     /**
      * Creates a webhook object from a payload.
      *
-     * @param  $payload
-     *
-     * @return Webhook
+     * @param string $payload JSON string containing webhook data
+     * @return static
      */
     public static function constructFromPayload($payload)
     {

lib/SSO.php

@@ -13,7 +13,7 @@ class SSO
     /**
      * Generates an OAuth 2.0 authorization URL used to initiate the SSO flow with WorkOS.
      *
-     * @param null|string $domain Domain of the user that will be going through SSO
+     * @param null|string $domain Domain of the user that will be going through SSO @deprecated 1.5.0 Use $connection or $organization instead.
      * @param null|string $redirectUri URI to direct the user to upon successful completion of SSO
      * @param null|array $state Associative array containing state that will be returned from WorkOS as a json encoded string
      * @param null|string $provider Service provider that handles the identity of the user

lib/UserManagement.php

@@ -1096,6 +1096,7 @@ public function createPasswordReset(
     }
 
     /**
+     * @deprecated 4.9.0 Use `createPasswordReset` instead. This method will be removed in a future major version.
      * Create Password Reset Email.
      *
      * @param string $email The email of the user that wishes to reset their password.
@@ -1204,6 +1205,7 @@ public function createMagicAuth(
     }
 
     /**
+     * @deprecated 4.6.0 Use `createMagicAuth` instead. This method will be removed in a future major version.
      * Creates a one-time Magic Auth code and emails it to the user.
      *
      * @param string $email The email address the one-time code will be sent to.