v4.8.0.rst

Version 4.8.0

Release Date: Unreleased

4.8.0 release of CodeIgniter4

• Highlights
• BREAKING
  • Behavior Changes
  • Interface Changes
  • Method Signature Changes
  • Property Scope Changes
  • Method Scope Changes
  • Removed Deprecated Items
• Enhancements
  • Commands
  • Testing
  • Database
    • Query Builder
    • Forge
    • Others
  • Model
  • Libraries
  • Helpers and Functions
  • HTTP
  • Validation
  • Others
• Message Changes
• Changes
• Deprecations
• Bugs Fixed

Highlights

• TBD

BREAKING

Behavior Changes

• The static Boot::initializeConsole() method no longer handles the display of the console header. This is now handled within Console::run().

  If you have overridden Boot::initializeConsole(), you should remove any code related to displaying the console header, as this is now the responsibility of the Console class.

• Commands: The filter:check command now requires the HTTP method argument to be uppercase (e.g., spark filter:check GET / instead of spark filter:check get /).
• Database: The Postgre driver's $db->error()['code'] previously always returned ''. It now returns the 5-character SQLSTATE string for query and transaction failures (e.g., '42P01'), or '08006' for connection-level failures. Code that relied on $db->error()['code'] === '' will need updating.

• Filters: HTTP method matching for method-based filters is now case-sensitive. The keys in Config\Filters::$methods must exactly match the request method

  (e.g., GET, POST). Lowercase method names (e.g., post) will no longer match.

• Testing: Tests using the FeatureTestTrait must now use uppercase HTTP method names when performing a request when using the call() method directly

  (e.g., $this->call('GET', '/path') instead of $this->call('get', '/path')). Additionally, setting method-based routes using withRoutes() must also use uppercase method names (e.g., $this->withRoutes([['GET', 'home', 'Home::index']])).

Interface Changes

NOTE: If you've implemented your own classes that implement these interfaces from scratch, you will need to

update your implementations to include the new methods or method changes to ensure compatibility.

• Logging: CodeIgniter\Log\Handlers\HandlerInterface::handle() now requires a third parameter array $context = []. Any custom log handler that overrides handle() - whether implementing HandlerInterface directly or extending a built-in handler class - must add the parameter to its handle() method signature.
• Security: The SecurityInterface's verify() method now has a native return type of static.

Method Signature Changes

• CLI: The Console::run() method now accepts an optional array $tokens parameter. This allows you to pass an array of command tokens directly to the console runner, which is useful for testing or programmatically running commands. If not provided, it will default to using the global $argv.

• CodeIgniter: The deprecated parameters in methods have been removed:

  • CodeIgniter\CodeIgniter::handleRequest() no longer accepts the deprecated $cacheConfig and $returnResponse parameters.

    • $cacheConfig is no longer used and is now hard deprecated. A deprecation notice will be triggered if this is passed to the method.
    • $returnResponse is now removed since already deprecated and unused.
    • The updated method signature is now handleRequest(?RouteCollectionInterface $routes, ?Cache $cacheConfig = null).

  • CodeIgniter\CodeIgniter::gatherOutput() no longer accepts the deprecated $cacheConfig parameter.

    As this is the first parameter, custom uses of this method will need to be updated to remove the parameter.

• Config: CodeIgniter\Config\Services::request() no longer accepts any parameter.

• Database: The following methods have had their signatures updated to remove deprecated parameters:

  • CodeIgniter\Database\Forge::_createTable() no longer accepts the deprecated $ifNotExists parameter. The method signature is now _createTable(string $table, array $attributes).

Property Scope Changes

• HTTP: The following properties have changed their scope (visibility):

  • CodeIgniter\HTTP\RequestTrait::$ipAddress is now private (previously protected).

Method Scope Changes

• HTTP: The following methods have changed their scope (visibility):

  • CodeIgniter\HTTP\URI::setUri() is now private (previously public).
  • CodeIgniter\HTTP\URI::refreshPath() is now protected (previously public).
  • CodeIgniter\HTTP\SiteURI::refreshPath() is now protected (previously public).

Removed Deprecated Items

• Autoloader: Removed the following deprecated methods:

  • CodeIgniter\Autoloader\Autoloader::sanitizeFileName()
  • CodeIgniter\Autoloader\Autoloader::discoverComposerNamespaces()

• Bootstrap: The deprecated system/bootstrap.php file has been removed.

• Cache: Removed the following deprecated methods and constant:

  • CodeIgniter\Cache\Handlers\BaseHandler::RESERVED_CHARACTERS (deprecated since v4.1.5)
  • CodeIgniter\Cache\Handlers\FileHandler::writeFile() (deprecated since v4.6.0)
  • CodeIgniter\Cache\Handlers\FileHandler::deleteFile() (deprecated since v4.6.0)
  • CodeIgniter\Cache\Handlers\FileHandler::getDirFileInfo() (deprecated since v4.6.0)
  • CodeIgniter\Cache\Handlers\FileHandler::getFileInfo() (deprecated since v4.6.0)

• CLI: Removed the following properties and methods deprecated:

  • CodeIgniter\CLI\BaseCommand::getPad()
  • CodeIgniter\CLI\CLI::$readline_support
  • CodeIgniter\CLI\CLI::$wait_msg
  • CodeIgniter\CLI\CLI::isWindows()
  • CodeIgniter\CLI\GeneratorTrait::execute()

• CodeIgniter: Removed the following properties and methods deprecated:

  • CodeIgniter\CodeIgniter::$cacheTTL
  • CodeIgniter\CodeIgniter::$returnResponse
  • CodeIgniter\CodeIgniter::initializeKint()
  • CodeIgniter\CodeIgniter::detectEnvironment()
  • CodeIgniter\CodeIgniter::bootstrapEnvironment()
  • CodeIgniter\CodeIgniter::forceSecureAccess()
  • CodeIgniter\CodeIgniter::displayCache()
  • CodeIgniter\CodeIgniter::cache()
  • CodeIgniter\CodeIgniter::cachePage()
  • CodeIgniter\CodeIgniter::generateCacheName()
  • CodeIgniter\CodeIgniter::displayPerformanceMetrics()
  • CodeIgniter\CodeIgniter::determinePath()
  • CodeIgniter\CodeIgniter::callExit()
  • CodeIgniter\Test\MockCodeIgniter::callExit()

• Config: Removed the following property deprecated:

  • CodeIgniter\Config\BaseService::$services (deprecated since v4.5.0)

• Database: Removed the following properties and methods deprecated:

  • CodeIgniter\Database\BaseBuilder::setInsertBatch()
  • CodeIgniter\Database\BaseBuilder::setUpdateBatch()
  • CodeIgniter\Database\BaseBuilder::cleanClone()
  • CodeIgniter\Database\BaseConnection::$strictOn
  • CodeIgniter\Database\Forge::$createTableIfStr
  • CodeIgniter\Database\Seeder::$faker
  • CodeIgniter\Database\Seeder::faker()
  • CodeIgniter\Database\OCI8\Forge::$createTableIfStr
  • CodeIgniter\Database\OCI8\Forge::getError()
  • CodeIgniter\Database\SQLSRV\Forge::$createTableIfStr

• Debug: Removed the following deprecated properties and methods:

  • CodeIgniter\Debug\Toolbar\Collectors\BaseCollector::cleanPath() (deprecated since v4.2.0)
  • CodeIgniter\Debug\Exceptions::$ob_level (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::$viewPath (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::determineView() (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::render() (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::collectVars() (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::maskSensitiveData() (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::maskData() (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::cleanPath() (deprecated since v4.2.0)
  • CodeIgniter\Debug\Exceptions::describeMemory() (deprecated since v4.4.0)
  • CodeIgniter\Debug\Exceptions::highlightFile() (deprecated since v4.4.0)

• Exceptions: Removed the following static constructors of FrameworkException and its child classes:

  • CodeIgniter\Exceptions\DownloadException::forCannotSetCache()
  • CodeIgniter\Exceptions\FrameworkException::forMissingExtension()
  • CodeIgniter\Honeypot\Exceptions\HoneypotException::forNoHiddenValue()
  • CodeIgniter\HTTP\Exceptions\HTTPException::forInvalidSameSiteSetting()
  • CodeIgniter\Security\Exceptions\SecurityException::forInvalidSameSite()
  • CodeIgniter\Session\Exceptions\SessionException::forInvalidSameSiteSetting()

• Filters: Removed the following properties and methods deprecated:

  • CodeIgniter\Filters\Filters::$arguments (deprecated since v4.6.0)
  • CodeIgniter\Filters\Filters::$argumentsClass (deprecated since v4.6.0)
  • CodeIgniter\Filters\Filters::getArguments() (deprecated since v4.6.0)

• HTTP: Removed the following properties and methods deprecated:

  • CodeIgniter\HTTP\Message::getHeaders() (deprecated since v4.0.5)
  • CodeIgniter\HTTP\Message::getHeader() (deprecated since v4.0.5)
  • CodeIgniter\HTTP\RequestTrait::getEnv() (deprecated since v4.4.4)
  • CodeIgniter\HTTP\URI::$uriString (deprecated since v4.4.0)
  • CodeIgniter\HTTP\URI::$baseURL (deprecated since v4.4.0)
  • CodeIgniter\HTTP\URI::setBaseURL() (deprecated since v4.4.0)
  • CodeIgniter\HTTP\URI::getBaseURL() (deprecated since v4.4.0)
  • CodeIgniter\HTTP\URI::setScheme() (deprecated since v4.4.0)
  • CodeIgniter\HTTP\SiteURI::$segments (deprecated since v4.4.0)
  • CodeIgniter\HTTP\SiteURI::setBaseURL() (deprecated since v4.4.0)
  • CodeIgniter\HTTP\SiteURI::setURI() (deprecated since v4.4.0)

• Security: Removed the following properties and methods deprecated:

  • CodeIgniter\Security\SecurityInterface::sanitizeFilename() (deprecated since v4.6.2)
  • CodeIgniter\Security\Security::sanitizeFilename() (deprecated since v4.6.2)
  • CodeIgniter\Security\Security::$csrfProtection (deprecated since v4.4.0)
  • CodeIgniter\Security\Security::$tokenRandomize (deprecated since v4.4.0)
  • CodeIgniter\Security\Security::$tokenName (deprecated since v4.4.0)
  • CodeIgniter\Security\Security::$headerName (deprecated since v4.4.0)
  • CodeIgniter\Security\Security::$expires (deprecated since v4.4.0)
  • CodeIgniter\Security\Security::$regenerate (deprecated since v4.4.0)
  • CodeIgniter\Security\Security::$redirect (deprecated since v4.4.0)
  • CodeIgniter\Security\Security::$sameSite (deprecated since v4.4.0)

Enhancements

Commands

• You can now retrieve the last executed command in the console using the new Console::getCommand() method. This is useful for logging, debugging, or any situation where you need to know which command was run.

• CLI now supports the -- separator to mean that what follows are arguments, not options. This allows you to have arguments that start with - without them being treated as options.

  For example: spark my:command -- --myarg will pass --myarg as an argument instead of an option.

• CLI now supports options with values specified using an equals sign (e.g., --option=value) in addition to the existing space-separated syntax (e.g., --option value).

  This provides more flexibility in how you can pass options to commands.

• CLI now supports parsing array options written multiple times (e.g., --option=value1 --option=value2) into an array of values. This allows you to easily pass multiple values for the same option without needing to use a comma-separated string.

  When used with CLI::getOption(), an array option will return its last value (for example, in this case, value2). To retrieve all values for an array option, use CLI::getRawOption().

• Likewise, the command() function now also supports the above enhancements for command-line option parsing when using the function to run commands from code.

Testing

Database

• Added trustServerCertificate option to SQLSRV database connections in Config\Database. Set it to true to trust the server certificate without CA validation when using encrypted connections.

Query Builder

Forge

Others

• Added new timezone option to connection array in Config\Database config. This ensures consistent timestamps between model operations and database functions like NOW(). Supported drivers: MySQLi, Postgre, and OCI8. See :ref:`database-config-timezone` for details.
• Added :php:class:`UniqueConstraintViolationException <CodeIgniter\\Database\\Exceptions\\UniqueConstraintViolationException>` which extends DatabaseException and is thrown on duplicate key (unique constraint) violations across all database drivers. See :ref:`database-unique-constraint-violation`.
• Added $db->getLastException() which returns the typed exception even when DBDebug is false. See :ref:`database-get-last-exception`.
• Added DatabaseException::getDatabaseCode() returning the native driver error code as int|string; getCode() is constrained to int by PHP's Throwable interface and cannot carry string SQLSTATE codes.

Model

• Added new chunkRows() method to CodeIgniter\Model for processing large datasets in smaller chunks.
• Added new firstOrInsert() method to CodeIgniter\Model that finds the first row matching the given attributes or inserts a new one. See :ref:`model-first-or-insert`.

Libraries

• Context: This new feature allows you to easily set and retrieve normal or hidden contextual data for the current request. See :ref:`Context <context>` for details.
• Images:: Added support for the AVIF file format.
• Logging: Log handlers now receive the full context array as a third argument to handle(). When $logGlobalContext is enabled, the CI global context is available under the HandlerInterface::GLOBAL_CONTEXT_KEY key. Built-in handlers append it to the log output; custom handlers can use it for structured logging.
• Logging: Added :ref:`per-call context logging <logging-per-call-context>` with three new Config\Logger options ($logContext, $logContextTrace, $logContextUsedKeys). Per PSR-3, a Throwable in the exception context key is automatically normalized to a meaningful array. All options default to false.

Helpers and Functions

• :doc:`Array Helper </helpers/array_helper>` gained five new dot-path functions: :php:func:`dot_array_has()`, :php:func:`dot_array_set()`, :php:func:`dot_array_unset()`, :php:func:`dot_array_only()`, and :php:func:`dot_array_except()`.

HTTP

• Added SSEResponse class for streaming Server-Sent Events (SSE) over HTTP. See :ref:`server-sent-events`.

• Response and its child classes no longer require Config\App passed to their constructors.

  Consequently, CURLRequest's $config parameter is unused and will be removed in a future release.

• CLIRequest now supports the -- separator to mean that what follows are arguments, not options. This allows you to have arguments that start with - without them being treated as options.

  For example: php index.php command -- --myarg will pass --myarg as an argument instead of an option.

• CLIRequest now supports options with values specified using an equals sign (e.g., --option=value) in addition to the existing space-separated syntax (e.g., --option value).

  This provides more flexibility in how you can pass options to CLI requests.

• Added $enableStyleNonce and $enableScriptNonce options to Config\App to automatically add nonces to control whether to add nonces to style-* and script-* directives in the Content Security Policy (CSP) header when CSP is enabled. See :ref:`csp-control-nonce-generation` for details.

• URI now accepts an optional boolean second parameter in the constructor, defaulting to false, to control how the query string is parsed in instantiation.

  This is the behavior of ->useRawQueryString() brought into the constructor for convenience. Previously, you need to call $uri->useRawQueryString(true)->setURI($uri) to get this behavior. Now you can simply do new URI($uri, true).

• CLIRequest now supports parsing array options written multiple times (e.g., --option=value1 --option=value2) into an array of values. This allows you to easily pass multiple values for the same option without needing to use a comma-separated string.

  When used with CLIRequest::getOption(), an array option will return its last value (for example, in this case, value2). To retrieve all values for an array option, use CLIRequest::getRawOption().

Validation

• Custom rule methods that set an error via the &$error reference parameter now support the {field}, {param}, and {value} placeholders, consistent with language-file and setRule()/setRules() error messages.

Others

• Float and Double Casting: Added support for precision and rounding mode when casting to float or double in entities.
• Float and Double casting now throws CastException::forInvalidFloatRoundingMode() if an rounding mode other than up, down, even or odd is provided.

Message Changes

• Removed deprecated language keys tied to removed exception constructors:

  • Core.missingExtension (FrameworkException::forMissingExtension())
  • HTTP.cannotSetCache (DownloadException::forCannotSetCache())
  • HTTP.disallowedAction
  • HTTP.invalidSameSiteSetting (HTTPException::forInvalidSameSiteSetting())
  • Security.invalidSameSite (SecurityException::forInvalidSameSite())
  • Session.invalidSameSiteSetting (SessionException::forInvalidSameSiteSetting())

Changes

• Config: Added the md key for Config\Mimes::$mimes for Markdown files.

Deprecations

• CLI: The CLI::parseCommandLine() method is now deprecated and will be removed in a future release. The CLI class now uses the new CommandLineParser class to handle command-line argument parsing.
• CLI: Returning a non-integer exit code from a command is now deprecated and will trigger a deprecation notice. Command methods should return an integer exit code (e.g., 0 for success, non-zero for errors) to ensure proper behavior across all platforms.
• HTTP: The CLIRequest::parseCommand() method is now deprecated and will be removed in a future release. The CLIRequest class now uses the new CommandLineParser class to handle command-line argument parsing.
• HTTP: URI::setSilent() is now hard deprecated. This method was only previously marked as deprecated. It will now trigger a deprecation notice when used.

Bugs Fixed

See the repo's CHANGELOG.md for a complete list of bugs fixed.