Update deprecation notices

lib/AuditLogs.php

@@ -88,9 +88,9 @@ public function createExport($organizationId, $rangeStart, $rangeEnd, $actions =
         };
 
         if (!is_null($actors)) {
-            $msg = "'actors' is deprecated. Please use 'actorNames' instead'";
+            $msg = "'actors' is deprecated. Please use 'actorNames' instead.";
 
-            error_log($msg);
+            trigger_error($msg, E_USER_DEPRECATED);
 
             $params["actors"] = $actors;
         };

lib/MFA.php

@@ -28,12 +28,12 @@ public function enrollFactor(
         $enrollPath = "auth/factors/enroll";
 
         if (!isset($type)) {
-            $msg = "Incomplete arguments: Need to specify a type of factor";
+            $msg = "Incomplete arguments: Need to specify a type of factor.";
             throw new Exception\UnexpectedValueException($msg);
         }
 
         if ($type != "sms" && $type != "totp") {
-            $msg = "Type Parameter must either be 'sms' or 'totp'";
+            $msg = "Type Parameter must either be 'sms' or 'totp'.";
             throw new Exception\UnexpectedValueException($msg);
         }
 
@@ -82,15 +82,15 @@ public function challengeFactor(
         $smsTemplate = null
     ) {
         if (!isset($authenticationFactorId)) {
-            $msg = "Incomplete arguments: 'authentication_factor_id' is a required parameter";
+            $msg = "Incomplete arguments: 'authentication_factor_id' is a required parameter.";
             throw new Exception\UnexpectedValueException($msg);
         }
 
         $challengePath = "auth/factors/{$authenticationFactorId}/challenge";
 
         $params = [
-        "sms_template" => $smsTemplate
-    ];
+            "sms_template" => $smsTemplate
+        ];
 
         $response = Client::request(
             Client::METHOD_POST,
@@ -120,19 +120,19 @@ public function verifyFactor(
         $code
     ) {
         if (!isset($authenticationChallengeId) || !isset($code)) {
-            $msg = "Incomplete arguments: 'authenticationChallengeId' and 'code' are required parameters";
+            $msg = "Incomplete arguments: 'authenticationChallengeId' and 'code' are required parameters.";
             throw new Exception\UnexpectedValueException($msg);
         }
 
-        $msg = "'verifyFactor' is deprecated. Please use 'verifyChallenge' instead";
+        $msg = "'verifyFactor' is deprecated. Please use 'verifyChallenge' instead.";
 
-        error_log($msg);
+        trigger_error($msg, E_USER_DEPRECATED);
 
         $response = (new \WorkOS\MFA())
-    ->verifyChallenge(
-        $authenticationChallengeId,
-        $code
-    );
+            ->verifyChallenge(
+                $authenticationChallengeId,
+                $code
+            );
 
         return $response;
     }
@@ -151,15 +151,15 @@ public function verifyChallenge(
         $code
     ) {
         if (!isset($authenticationChallengeId) || !isset($code)) {
-            $msg = "Incomplete arguments: 'authenticationChallengeId' and 'code' are required parameters";
+            $msg = "Incomplete arguments: 'authenticationChallengeId' and 'code' are required parameters.";
             throw new Exception\UnexpectedValueException($msg);
         }
 
         $verifyPath = "auth/challenges/{$authenticationChallengeId}/verify";
 
         $params = [
-        "code" => $code
-    ];
+            "code" => $code
+        ];
 
         $response = Client::request(
             Client::METHOD_POST,

lib/Organizations.php

@@ -89,12 +89,20 @@ public function createOrganization(
         $params = ["name" => $name];
 
         if (isset($domains)) {
+            $msg = "'domains' is deprecated. Please use 'domain_data' instead.";
+
+            trigger_error($msg, E_USER_DEPRECATED);
+
             $params["domains"] = $domains;
         }
         if (isset($domain_data)) {
             $params["domain_data"] = $domain_data;
         }
         if (isset($allowProfilesOutsideOrganization)) {
+            $msg = "'allowProfilesOutsideOrganization' is deprecated. If you need to allow sign-ins from any email domain, contact [email protected].";
+
+            trigger_error($msg, E_USER_DEPRECATED);
+
             $params["allow_profiles_outside_organization"] = $allowProfilesOutsideOrganization;
         }
         if (isset($externalId)) {
@@ -139,12 +147,20 @@ public function updateOrganization(
         $params = ["name" => $name];
 
         if (isset($domains)) {
+            $msg = "'domains' is deprecated. Please use 'domain_data' instead.";
+
+            trigger_error($msg, E_USER_DEPRECATED);
+
             $params["domains"] = $domains;
         }
         if (isset($domain_data)) {
             $params["domain_data"] = $domain_data;
         }
         if (isset($allowProfilesOutsideOrganization)) {
+            $msg = "'allowProfilesOutsideOrganization' is deprecated. If you need to allow sign-ins from any email domain, contact [email protected].";
+
+            trigger_error($msg, E_USER_DEPRECATED);
+
             $params["allow_profiles_outside_organization"] = $allowProfilesOutsideOrganization;
         }
         if (isset($stripeCustomerId)) {

lib/Resource/BaseWorkOSResource.php

@@ -76,7 +76,7 @@ public function __set($key, $value)
             $this->values[$key] = $value;
         }
 
-        $msg = "{$key} does not exist on " . static::class;
+        $msg = "{$key} does not exist on " . static::class . ".";
         throw new \WorkOS\Exception\UnexpectedValueException($msg);
     }
 
@@ -100,7 +100,7 @@ public function &__get($key)
             return $this->raw[$key];
         }
 
-        $msg = "{$key} does not exist on " . static::class;
+        $msg = "{$key} does not exist on " . static::class . ".";
         throw new \WorkOS\Exception\UnexpectedValueException($msg);
     }
 }

lib/Resource/DirectoryUser.php

@@ -65,6 +65,10 @@ class DirectoryUser extends BaseWorkOSResource
      */
     public function primaryEmail()
     {
+        $msg = "'primaryEmail' is deprecated. Please use 'email' instead.";
+
+        trigger_error($msg, E_USER_DEPRECATED);
+
         $response = $this;
 
         if (count($response->raw["emails"]) == 0) {

lib/SSO.php

@@ -40,15 +40,15 @@ public function getAuthorizationUrl(
         $authorizationPath = "sso/authorize";
 
         if (!isset($domain) && !isset($provider) && !isset($connection) && !isset($organization)) {
-            $msg = "Either \$domain, \$provider, \$connection, or \$organization is required";
+            $msg = "Either \$domain, \$provider, \$connection, or \$organization is required.";
 
             throw new Exception\UnexpectedValueException($msg);
         }
 
         if (isset($domain)) {
-            $msg = "Domain is being deprecated, please switch to using Connection or Organization ID";
+            $msg = "'domain' is being deprecated, please switch to using 'connection' or 'organization'.";
 
-            error_log($msg);
+            trigger_error($msg, E_USER_DEPRECATED);
         }
 
         $params = [

lib/UserManagement.php

@@ -33,7 +33,6 @@ class UserManagement
      *
      * @return Resource\User
      */
-
     public function createUser(
         $email,
         $password = null,
@@ -627,7 +626,7 @@ public function getAuthorizationUrl(
         $path = "user_management/authorize";
 
         if (!isset($provider) && !isset($connectionId) && !isset($organizationId)) {
-            $msg = "Either \$provider, \$connectionId, or \$organizationId is required";
+            $msg = "Either \$provider, \$connectionId, or \$organizationId is required.";
             throw new Exception\UnexpectedValueException($msg);
         }
 
@@ -640,7 +639,7 @@ public function getAuthorizationUrl(
         ];
 
         if (isset($provider) && !\in_array($provider, $supportedProviders)) {
-            $msg = "Only " . implode("','", $supportedProviders) . " providers are supported";
+            $msg = "Only " . implode("','", $supportedProviders) . " providers are supported.";
             throw new Exception\UnexpectedValueException($msg);
         }
 
@@ -1110,7 +1109,7 @@ public function sendPasswordResetEmail($email, $passwordResetUrl)
     {
         $msg = "'sendPasswordResetEmail' is deprecated. Please use 'createPasswordReset' instead. This method will be removed in a future major version.";
 
-        error_log($msg);
+        trigger_error($msg, E_USER_DEPRECATED);
 
         $path = "user_management/password_reset/send";
 
@@ -1224,7 +1223,7 @@ public function sendMagicAuthCode($email)
 
         $msg = "'sendMagicAuthCode' is deprecated. Please use 'createMagicAuth' instead. This method will be removed in a future major version.";
 
-        error_log($msg);
+        trigger_error($msg, E_USER_DEPRECATED);
 
         $response = Client::request(
             Client::METHOD_POST,
@@ -1261,17 +1260,17 @@ public function getJwksUrl(string $clientId)
      * Returns the logout URL to end a user's session and redirect to your home page.
      *
      * @param string $sessionId The session ID of the user.
-     * @param string $return_to The URL to redirect to after the user logs out.
+     * @param string|null $return_to The URL to redirect to after the user logs out.
      *
      * @return string
      */
-    public function getLogoutUrl(string $sessionId, string $return_to = null)
+    public function getLogoutUrl(string $sessionId, ?string $return_to = null)
     {
         if (!isset($sessionId) || empty($sessionId)) {
             throw new Exception\UnexpectedValueException("sessionId must not be empty");
         }
 
-        $params = [ "session_id" => $sessionId ];
+        $params = ["session_id" => $sessionId];
         if ($return_to) {
             $params["return_to"] = $return_to;
         }

lib/WorkOS.php

@@ -48,7 +48,7 @@ public static function getApiKey()
             return self::$apiKey;
         }
 
-        $msg = "\$apiKey is required";
+        $msg = "\$apiKey is required.";
         throw new \WorkOS\Exception\ConfigurationException($msg);
     }
 
@@ -76,7 +76,7 @@ public static function getClientId()
             return self::$clientId;
         }
 
-        $msg = "\$clientId is required";
+        $msg = "\$clientId is required.";
         throw new \WorkOS\Exception\ConfigurationException($msg);
     }
 

phpunit.xml

@@ -1,7 +1,9 @@
-<phpunit bootstrap="tests/bootstrap.php" colors="true">
+<phpunit bootstrap="tests/bootstrap.php" colors="true"
+    displayDetailsOnTestsThatTriggerDeprecations="true"
+    displayDetailsOnTestsThatTriggerWarnings="true">
     <testsuites>
         <testsuite name="WorkOS PHP Test Suite">
             <directory suffix="Test.php">tests</directory>
         </testsuite>
     </testsuites>
-</phpunit>
+</phpunit>

tests/TestHelper.php

@@ -2,9 +2,18 @@
 
 namespace WorkOS;
 
+use WorkOS\Client;
+
 trait TestHelper
 {
+    /**
+     * @var \WorkOS\RequestClient\RequestClientInterface
+     */
     protected $defaultRequestClient;
+
+    /**
+     * @var \PHPUnit\Framework\MockObject\MockObject
+     */
     protected $requestClientMock;
 
     protected function setUp(): void
@@ -106,4 +115,34 @@ private function prepareRequestMock($method, $url, $headers, $params)
                 static::identicalTo($params)
             );
     }
+
+    /**
+     * Asserts that a specific deprecation warning is triggered when callable is executed
+     *
+     * @param string $expected_warning The expected deprecation message
+     * @param callable $callable The function or method that should trigger the deprecation
+     * @return mixed The return value from the callable
+     */
+    protected function assertDeprecationTriggered(string $expected_warning, callable $callable)
+    {
+        $caught = false;
+
+        set_error_handler(function ($errno, $errstr) use ($expected_warning, &$caught) {
+            if ($errno === E_USER_DEPRECATED && $errstr === $expected_warning) {
+                $caught = true;
+                return true;
+            }
+            return false;
+        });
+
+        $result = $callable();
+
+        restore_error_handler();
+
+        if (!$caught) {
+            $this->fail('Expected deprecation warning was not triggered: ' . $expected_warning);
+        }
+
+        return $result;
+    }
 }