|
| 1 | +# Phalcon Runtime Upgrades |
| 2 | + |
| 3 | +Use this guide when moving a PhalconKit application or the core package to a |
| 4 | +new native Phalcon patch or minor release. |
| 5 | + |
| 6 | +This is separate from the `zemit-cms/core` package rename and the old RESTful |
| 7 | +resource migration. Runtime upgrades are mostly dependency, extension, |
| 8 | +static-analysis, CI, and compatibility-review work. |
| 9 | + |
| 10 | +## When To Use This |
| 11 | + |
| 12 | +Use this checklist when changing any of these values: |
| 13 | + |
| 14 | +- the installed `phalcon` PHP extension; |
| 15 | +- the Composer `ext-phalcon` platform requirement; |
| 16 | +- `phalcon/ide-stubs`; |
| 17 | +- Docker `PHALCON_VERSION` build arguments; |
| 18 | +- CI Phalcon install URLs or extension cache keys. |
| 19 | + |
| 20 | +Keep those changes in one focused commit where possible. Avoid mixing a runtime |
| 21 | +upgrade with unrelated model, controller, schema, or API behavior changes. |
| 22 | + |
| 23 | +## Phalcon 5.14.2 Checklist |
| 24 | + |
| 25 | +For the 5.14.2 line, align the package and runtime on: |
| 26 | + |
| 27 | +```json |
| 28 | +{ |
| 29 | + "require": { |
| 30 | + "ext-phalcon": "^5.14.2" |
| 31 | + }, |
| 32 | + "require-dev": { |
| 33 | + "phalcon/ide-stubs": "^5.14.2" |
| 34 | + } |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +Applications that keep `phalcon/ide-stubs` only under `suggest` or in a |
| 39 | +separate development tooling package should still update the same version floor |
| 40 | +there so IDE and analyzer signatures match the installed extension. |
| 41 | + |
| 42 | +## Local Runtime |
| 43 | + |
| 44 | +Install the native extension first, then verify the CLI PHP runtime that |
| 45 | +Composer and QA tools will use: |
| 46 | + |
| 47 | +```shell |
| 48 | +php -r 'echo phpversion("phalcon") ?: "not installed"; echo PHP_EOL;' |
| 49 | +php --ri phalcon |
| 50 | +composer check-platform-reqs |
| 51 | +``` |
| 52 | + |
| 53 | +If a machine has multiple PHP binaries, run those checks with the same binary |
| 54 | +used by Composer, PHP-FPM, Swoole workers, and CLI tasks. Do not rely on web |
| 55 | +server PHP and CLI PHP having the same extension version unless both are |
| 56 | +checked. |
| 57 | + |
| 58 | +## Composer And Stubs |
| 59 | + |
| 60 | +For PhalconKit core, update tracked Composer constraints and leave ignored |
| 61 | +local lock/vendor changes out of the release commit unless the repository |
| 62 | +explicitly tracks them. |
| 63 | + |
| 64 | +For applications that track `composer.lock`, update the lock file too: |
| 65 | + |
| 66 | +```shell |
| 67 | +composer update phalcon/ide-stubs phalcon-kit/core --with-dependencies |
| 68 | +composer check-platform-reqs |
| 69 | +``` |
| 70 | + |
| 71 | +When preparing Composer metadata before the new extension is installed, the |
| 72 | +temporary lock refresh can ignore only the not-yet-installed platform |
| 73 | +requirements: |
| 74 | + |
| 75 | +```shell |
| 76 | +composer update phalcon/ide-stubs --with-dependencies --ignore-platform-req=ext-phalcon |
| 77 | +``` |
| 78 | + |
| 79 | +Add other `--ignore-platform-req` flags only for extensions that are unrelated |
| 80 | +to the upgrade and genuinely absent from the local CLI PHP runtime. Run |
| 81 | +`composer check-platform-reqs` again after the real extension is installed. |
| 82 | + |
| 83 | +If the application does not update `phalcon-kit/core` in the same change, still |
| 84 | +update `phalcon/ide-stubs` so Psalm, PHPStan, and IDEs analyze against the same |
| 85 | +native API version as the runtime. |
| 86 | + |
| 87 | +## Docker And CI |
| 88 | + |
| 89 | +Update every runtime image and CI pin that installs Phalcon: |
| 90 | + |
| 91 | +- Docker `ARG PHALCON_VERSION`; |
| 92 | +- GitHub Actions or other CI `PHALCON_VERSION`; |
| 93 | +- PECL or GitHub release tarball URLs; |
| 94 | +- extension cache keys that include the Phalcon version; |
| 95 | +- image tags or build cache keys derived from PHP and Phalcon versions. |
| 96 | + |
| 97 | +After changing CI pins, confirm the install URL resolves before relying on the |
| 98 | +workflow. A redirect from the GitHub release asset URL is enough for the |
| 99 | +installer used by this repository. |
| 100 | + |
| 101 | +## Application Compatibility Review |
| 102 | + |
| 103 | +Patch-level Phalcon upgrades are usually small, but PhalconKit applications |
| 104 | +should review these recurring integration boundaries: |
| 105 | + |
| 106 | +- Replace deprecated `Phalcon\Events\ManagerInterface` and |
| 107 | + `Phalcon\Events\EventInterface` references in application-owned contracts with |
| 108 | + `Phalcon\Contracts\Events\Manager` and `Phalcon\Contracts\Events\Event`. |
| 109 | +- Keep native Phalcon setter boundaries honest. If a native method still |
| 110 | + requires a concrete `Phalcon\Events\Manager`, guard or type the value there |
| 111 | + instead of passing only a broader contract. |
| 112 | +- Keep mailer config canonical and lower-case, especially |
| 113 | + `MAILER_SMTP_ENCRYPTION=ssl` or `tls`. PhalconKit normalizes common casing, |
| 114 | + but lowercase config keeps app examples and deploy variables unambiguous. |
| 115 | +- Validate app config for provider options that become network behavior later, |
| 116 | + such as mailer driver, SMTP encryption, host, port, username, and adapter |
| 117 | + class names. |
| 118 | +- If overriding REST/query policy setters or merge helpers, keep signatures |
| 119 | + widened to the current `array|\Phalcon\Support\Collection|null` contracts. |
| 120 | +- If using `modelHasColumn()`, keep application PHPDoc aligned with its nullable |
| 121 | + model-name contract. The helper returns `false` for missing or invalid model |
| 122 | + names instead of requiring a strict `class-string`. |
| 123 | + |
| 124 | +## Validation |
| 125 | + |
| 126 | +Run the smallest useful checks before the extension is installed, then run the |
| 127 | +runtime checks after installation. |
| 128 | + |
| 129 | +Before installing the new extension: |
| 130 | + |
| 131 | +```shell |
| 132 | +composer validate --strict --no-check-publish |
| 133 | +git diff --check |
| 134 | +``` |
| 135 | + |
| 136 | +After installing the new extension: |
| 137 | + |
| 138 | +```shell |
| 139 | +composer check-platform-reqs |
| 140 | +composer phpcs |
| 141 | +composer psalm |
| 142 | +composer psalm:taint |
| 143 | +composer phpunit |
| 144 | +``` |
| 145 | + |
| 146 | +For a public release, run the full release gate from |
| 147 | +[Quality And Maintenance](quality-and-maintenance.md) and follow |
| 148 | +[Release Process](release.md). |
0 commit comments