chore: test that @deprecated items have version numbers

contributing/internals.md

@@ -44,6 +44,31 @@ afraid to use it when it's needed and can help things.
 -   Start simple, refactor as necessary to achieve clean separation of
     code, but don't overdo it.
 
+## Deprecations
+
+Deprecations happen when code no longer fits its purpose or is superseded by better solutions.
+In such cases, it's important that deprecations are documented clearly to guide developers during
+their upgrade process.
+
+- Add `@deprecated` tags in the doc block of deprecated functions, methods, classes, etc. Include
+    the version number where the deprecation was introduced, a description of why it's deprecated,
+    and recommended replacement(s), if any. If there are multiple alternative approaches, list all of them.
+
+- Do not add `@deprecated` tags to a function/method if you only mean to deprecate its parameter(s).
+    This will cause the whole function/method to be marked as deprecated by IDEs. Instead, trigger
+    a deprecation inside the function/method body if those parameters are passed. Ensure to include
+    the version number since when the deprecation occurred. Optionally, but encouraged, add a `@todo`
+    comment so that it can be found later on.
+
+- User-facing deprecation warnings should also be triggered via the framework's deprecation handling
+    mechanism (e.g., `@trigger_error()` or error log entries) to alert end users.
+
+- Do not add new tests for deprecated code paths. Instead, use tools and static analysis to ensure
+    that no code within the framework or official packages is using the deprecated functionality.
+
+- Document all deprecations in the changelog file for that release, under a "Deprecations"
+    section, so users are informed when upgrading.
+
 ## Testing
 
 Any new packages submitted to the framework must be accompanied by unit

system/HTTP/Message.php

@@ -65,7 +65,7 @@ public function getBody()
      *
      * @return array<string, Header> An array of the request headers
      *
-     * @deprecated Use Message::headers() to make room for PSR-7
+     * @deprecated 4.0.5 Use Message::headers() to make room for PSR-7
      *
      * @TODO Incompatible return value with PSR-7
      *
@@ -82,7 +82,7 @@ public function getHeaders(): array
      *
      * @return array|Header|null
      *
-     * @deprecated Use Message::header() to make room for PSR-7
+     * @deprecated 4.0.5 Use Message::header() to make room for PSR-7
      *
      * @TODO Incompatible return value with PSR-7
      *

system/HTTP/OutgoingRequest.php

@@ -82,7 +82,7 @@ public function getMethod(): string
      *
      * @return $this
      *
-     * @deprecated Use withMethod() instead for immutability
+     * @deprecated 4.3.0 Use withMethod() instead for immutability
      */
     public function setMethod(string $method)
     {

system/HTTP/RequestTrait.php

@@ -39,7 +39,7 @@ trait RequestTrait
      *
      * @var string
      *
-     * @deprecated Will become private in a future release
+     * @deprecated 4.0.5 Will become private in a future release
      */
     protected $ipAddress = '';
 

system/HTTP/SiteURI.php

@@ -70,7 +70,7 @@ class SiteURI extends URI
      *
      * @var array<int, string>
      *
-     * @deprecated This property will be private.
+     * @deprecated 4.4.0 This property will be private.
      */
     protected $segments;
 
@@ -220,15 +220,15 @@ private function setBasePath(): void
     }
 
     /**
-     * @deprecated
+     * @deprecated 4.4.0
      */
     public function setBaseURL(string $baseURL): void
     {
         throw new BadMethodCallException('Cannot use this method.');
     }
 
     /**
-     * @deprecated
+     * @deprecated 4.4.0
      */
     public function setURI(?string $uri = null)
     {
@@ -312,7 +312,7 @@ private function convertToSegments(string $path): array
      *
      * @return $this
      *
-     * @deprecated This method will be private.
+     * @deprecated 4.4.0 This method will be private.
      */
     public function refreshPath()
     {

system/HTTP/URI.php

@@ -657,7 +657,7 @@ public function __toString(): string
      *
      * @return array{string, string}
      *
-     * @deprecated This method will be deleted.
+     * @deprecated 4.2.0 This method will be deleted.
      */
     private function changeSchemeAndPath(string $scheme, string $path): array
     {
@@ -840,7 +840,7 @@ public function setPath(string $path)
      *
      * @interal
      *
-     * @deprecated Use SiteURI instead.
+     * @deprecated 4.4.0 Use SiteURI instead.
      */
     public function setBaseURL(string $baseURL): void
     {
@@ -852,7 +852,7 @@ public function setBaseURL(string $baseURL): void
      *
      * @interal
      *
-     * @deprecated Use SiteURI instead.
+     * @deprecated 4.4.0 Use SiteURI instead.
      */
     public function getBaseURL(): string
     {
@@ -868,7 +868,7 @@ public function getBaseURL(): string
      *
      * @return $this
      *
-     * @deprecated This method will be private.
+     * @deprecated 4.4.0 This method will be private.
      */
     public function refreshPath()
     {

system/I18n/TimeLegacy.php

@@ -42,7 +42,7 @@
  *
  * @phpstan-consistent-constructor
  *
- * @deprecated Use Time instead.
+ * @deprecated 4.3.0 Use Time instead.
  * @see \CodeIgniter\I18n\TimeLegacyTest
  */
 class TimeLegacy extends DateTime

system/I18n/TimeTrait.php

@@ -292,7 +292,7 @@ public static function createFromInstance(DateTimeInterface $dateTime, ?string $
      *
      * @throws Exception
      *
-     * @deprecated         Use createFromInstance() instead
+     * @deprecated 4.3.0 Use createFromInstance() instead
      *
      * @codeCoverageIgnore
      */

system/Language/en/Email.php

@@ -34,6 +34,7 @@
     'SMTPAuthPassword'      => 'Failed to authenticate password. Error: {0}',
     'SMTPDataFailure'       => 'Unable to send data: {0}',
     'exitStatus'            => 'Exit status code: {0}',
-    // @deprecated
+
+    // @deprecated v4.7.0
     'failedSMTPLogin' => 'Failed to send AUTH LOGIN command. Error: {0}',
 ];

system/Language/en/HTTP.php

@@ -58,7 +58,7 @@
     'localeNotSupported' => 'Locale is not supported: {0}',
 
     // CSRF
-    // @deprecated use 'Security.disallowedAction'
+    // @deprecated 4.0.5 use 'Security.disallowedAction'
     'disallowedAction' => 'The action you requested is not allowed.',
 
     // Uploaded file moving

system/Language/en/Images.php

@@ -33,6 +33,6 @@
     'invalidDirection'       => 'Flip direction can be only "vertical" or "horizontal". Given: "{0}"',
     'exifNotSupported'       => 'Reading EXIF data is not supported by this PHP installation.',
 
-    // @deprecated
+    // @deprecated 4.7.0
     'libPathInvalid' => 'The path to your image library is not correct. Please set the correct path in your image preferences. "{0}"',
 ];

system/Router/AutoRouter.php

@@ -166,7 +166,7 @@ public function getRoute(string $uri, string $httpVerb): array
      * Tells the system whether we should translate URI dashes or not
      * in the URI from a dash to an underscore.
      *
-     * @deprecated This method should be removed.
+     * @deprecated 4.2.0 This method should be removed.
      */
     public function setTranslateURIDashes(bool $val = false): self
     {
@@ -238,7 +238,7 @@ private function isValidSegment(string $segment): bool
      *
      * @param bool $validate if true, checks to make sure $dir consists of only PSR4 compliant segments
      *
-     * @deprecated This method should be removed.
+     * @deprecated 4.2.0 This method should be removed.
      *
      * @return void
      */
@@ -271,7 +271,7 @@ public function setDirectory(?string $dir = null, bool $append = false, bool $va
      * Returns the name of the sub-directory the controller is in,
      * if any. Relative to APPPATH.'Controllers'.
      *
-     * @deprecated This method should be removed.
+     * @deprecated 4.2.0 This method should be removed.
      */
     public function directory(): string
     {

system/Router/RouteCollection.php

@@ -1255,7 +1255,7 @@ public function reverseRoute(string $search, ...$params)
     /**
      * Replaces the {locale} tag with the current application locale
      *
-     * @deprecated Unused.
+     * @deprecated 4.3.0 Unused.
      */
     protected function localizeRoute(string $route): string
     {
@@ -1309,7 +1309,7 @@ public function getFiltersForRoute(string $search, ?string $verb = null): array
      *
      * @throws RouterException
      *
-     * @deprecated Unused. Now uses buildReverseRoute().
+     * @deprecated 4.3.0 Unused. Now uses buildReverseRoute().
      */
     protected function fillRouteParams(string $from, ?array $params = null): string
     {

system/Router/Router.php

@@ -384,7 +384,7 @@ public function setIndexPage($page): self
      * Tells the system whether we should translate URI dashes or not
      * in the URI from a dash to an underscore.
      *
-     * @deprecated This method should be removed.
+     * @deprecated 4.2.0 This method should be removed.
      */
     public function setTranslateURIDashes(bool $val = false): self
     {
@@ -601,7 +601,7 @@ public function autoRoute(string $uri)
      *
      * @return array returns an array of remaining uri segments that don't map onto a directory
      *
-     * @deprecated this function name does not properly describe its behavior so it has been deprecated
+     * @deprecated 4.1.2 this function name does not properly describe its behavior so it has been deprecated
      *
      * @codeCoverageIgnore
      */
@@ -617,7 +617,7 @@ protected function validateRequest(array $segments): array
      *
      * @return array returns an array of remaining uri segments that don't map onto a directory
      *
-     * @deprecated Not used. Moved to AutoRouter class.
+     * @deprecated 4.2.0 Not used. Moved to AutoRouter class.
      */
     protected function scanControllers(array $segments): array
     {
@@ -665,7 +665,7 @@ protected function scanControllers(array $segments): array
      *
      * @return void
      *
-     * @deprecated This method should be removed.
+     * @deprecated 4.2.0 This method should be removed.
      */
     public function setDirectory(?string $dir = null, bool $append = false, bool $validate = true)
     {
@@ -683,7 +683,7 @@ public function setDirectory(?string $dir = null, bool $append = false, bool $va
      *
      * regex comes from https://www.php.net/manual/en/language.variables.basics.php
      *
-     * @deprecated Moved to AutoRouter class.
+     * @deprecated 4.2.0 Moved to AutoRouter class.
      */
     private function isValidSegment(string $segment): bool
     {
@@ -725,7 +725,7 @@ protected function setRequest(array $segments = [])
     /**
      * Sets the default controller based on the info set in the RouteCollection.
      *
-     * @deprecated This was an unnecessary method, so it is no longer used.
+     * @deprecated 4.2.0 This was an unnecessary method, so it is no longer used.
      *
      * @return void
      */