release: v11.0.0 - M3 resource-to-object migration complete

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to the PHP Firebird Extension will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - v11.0 M3 Resource-to-Object Migration
+## [11.0.0] - 2026-04-09
 
 ### Added
 - **[M3 Phase A+B]** Skeleton class entries for `Firebird\Connection`, `Firebird\Transaction`,
@@ -69,6 +69,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   type changed from `mixed` to `\Firebird\Service|false`. All 14 service PHPTs pass; stubs
   sync clean. **Phase I completes the M3 resource-to-object migration sweep.**
 
+### Documentation
+- **Migration guide**: `docs/MIGRATION-v10-to-v11.md` — comprehensive before/after examples for
+  all 6 object type changes, `instanceof` reference table, and PHPStan stubs setup. Closes #216.
+
 ### Breaking Changes (v11.0)
 - Return types of `fbird_connect()`, `fbird_pconnect()`, `fbird_create_database()`,
   `fbird_trans()`, `fbird_trans_start()`, `fbird_blob_create()`, `fbird_blob_open()`,
@@ -1346,7 +1350,8 @@ grep -r "ibase\." config/
 - [Upstream Issues Analysis](docs/UPSTREAM_ISSUE_ANALYSIS.md)
 - [Development History](docs/DEVELOPMENT_HISTORY.md)
 
-[Unreleased]: https://github.com/satwareAG/php-firebird/compare/v10.6.2...HEAD
+[Unreleased]: https://github.com/satwareAG/php-firebird/compare/v11.0.0...HEAD
+[11.0.0]: https://github.com/satwareAG/php-firebird/compare/v10.6.2...v11.0.0
 [10.6.2]: https://github.com/satwareAG/php-firebird/compare/v10.6.1...v10.6.2
 [10.6.1]: https://github.com/satwareAG/php-firebird/compare/v10.6.0...v10.6.1
 [10.6.0]: https://github.com/satwareAG/php-firebird/compare/v10.3.9...v10.6.0

NEXT_STEPS.md

@@ -1,6 +1,6 @@
 # Next Steps - php-firebird
 
-**Last Updated**: 2026-04-09 AM (PHPStan fix pushed - PR #215 ready for review)
+**Last Updated**: 2026-04-09 PM (PR #215 merged, v11.0.0 release prep in progress)
 
 ## Immediate (v10.6.x)
 
@@ -15,7 +15,7 @@
 Tracked via GitHub issues #175-#179 (milestone: v11.0 - Modernization, due 2026-12-31):
 
 - [x] #175 - [M2] Migrate all 84 procedural arginfo to typed return macros (CLOSED)
-- [ ] #176 - [M3] Resource-to-object migration for Layer 1 procedural functions (breaking change)
+- [x] #176 - [M3] Resource-to-object migration for Layer 1 procedural functions (MERGED via PR #215)
   - [x] Phase A+B (`7f100f6`): Class skeletons - Firebird\Connection, \Transaction, \Event, \Batch
   - [x] Phase C (`1b37219`): fbird_connect/pconnect/create_database return Firebird\Connection
   - [x] Phase D (`508f75e`): fbird_trans/trans_start return Firebird\Transaction
@@ -45,24 +45,13 @@ All previously open specs confirmed RELEASED and closed (2026-04-07 audit):
 - [ ] macOS x86_64 builds disabled (macos-13 runner deprecated) - evaluate macos-15 x86_64 when available
 - [ ] Coverage threshold still at 54% - target 65%+ with v11.0 test improvements
 
-## 2026-04-09 AM - PHPStan Code Quality Fix
+## 2026-04-09 AM - PHPStan Code Quality Fix (COMPLETE)
 
-**Branch**: `feat/20260408_morning_start` - PR #215 open, CI running.
+**PR #215 merged** (squash, ff84b3a). M3 Phases A-I complete. #176 closed.
 
-### PHPStan errors fixed (`f615a61`)
-
-- `phpstan/firebird-event.stub.php`: removed duplicate `Firebird\Event` / `Firebird\Exception`
-  declarations (both already in `stubs/firebird-classes.php` which is also a PHPStan stubFile)
-- `src/Firebird/functions.php`: updated `fbird_query_params_tx()` `@param $transaction` to
-  `\Firebird\Transaction|resource` (dual-accept bridge - callers pass objects post-M3)
-- `src/Firebird/functions.php`: updated `fbird_trans_begin()` `@return`/`@var` to
-  `\Firebird\Transaction|false` (stale `resource|false` annotation from pre-M3)
-
-### Next actions
-
-1. Confirm Code Quality CI green for `f615a61`
-2. Merge PR #215 into `satware-main`
-3. Close issue #176
+- PHPStan stub fixes: duplicate class declarations removed, `@return`/`@param` updated for M3
+- PHPCS fix: `Database.php` constructor `) {` on same line (PSR-12)
+- Stale open PRs #209/#210/#211 rebased and merged (v11 housekeeping)
 
 ## 2026-04-08 EOD - M3 Phase I + CI Fix
 

VERSION.txt

@@ -1 +1 @@
-10.6.2
+11.0.0

docs/MIGRATION-v10-to-v11.md

@@ -0,0 +1,212 @@
+# Migration Guide: v10.x to v11.0
+
+> v11.0 is a **breaking change** release. All `fbird_*` procedural functions that
+> previously returned PHP `resource` handles now return typed `Firebird\*` objects.
+
+## PHP Version Requirement
+
+v11.0 requires **PHP 8.2+**. PHP 8.1 reached end-of-life in November 2024.
+
+## What Changed
+
+| Function(s) | v10 return type | v11 return type |
+|-------------|-----------------|-----------------|
+| `fbird_connect()`, `fbird_pconnect()`, `fbird_create_database()` | `resource\|false` | `Firebird\Connection\|false` |
+| `fbird_trans()`, `fbird_trans_start()` | `resource\|false` | `Firebird\Transaction\|false` |
+| `fbird_query()`, `fbird_execute()` | `resource\|false` | `Firebird\ResultSet\|false` |
+| `fbird_blob_create()`, `fbird_blob_open()`, `fbird_blob_create_seekable()`, `fbird_blob_open_seekable()` | `resource\|false` | `Firebird\Blob\|false` |
+| `fbird_set_event_handler()`, `fbird_wait_event()` | `resource\|false` | `Firebird\Event\|false` |
+| `fbird_service_attach()` | `resource\|false` | `Firebird\Service\|false` |
+
+All consuming functions (`fbird_commit()`, `fbird_rollback()`, `fbird_close()`,
+`fbird_query()`, `fbird_fetch_row()`, etc.) accept **both** the new objects and
+legacy `resource` handles via dual-accept bridges. This eases gradual migration.
+
+## Breaking Change: `is_resource()` Checks
+
+The most common breaking change is code that tests connection or result handles
+with `is_resource()`. Objects are not resources, so these checks will now return
+`false` even for valid handles.
+
+```php
+// v10 - BREAKS in v11
+$conn = fbird_connect($dsn, $user, $pass);
+if (is_resource($conn)) {
+    // ...
+}
+
+// v11 - correct
+$conn = fbird_connect($dsn, $user, $pass);
+if ($conn instanceof \Firebird\Connection) {
+    // ...
+}
+
+// v11 - works for both old and new code
+$conn = fbird_connect($dsn, $user, $pass);
+if ($conn !== false) {
+    // simplest pattern - just check for false
+}
+```
+
+## Migration by Function Family
+
+### Connection Functions
+
+```php
+// v10
+$dbh = fbird_connect('localhost:/var/db/test.fdb', 'SYSDBA', 'masterkey');
+if (!is_resource($dbh)) {
+    die(fbird_errmsg());
+}
+fbird_close($dbh);
+
+// v11
+$dbh = fbird_connect('localhost:/var/db/test.fdb', 'SYSDBA', 'masterkey');
+if ($dbh === false) {
+    die(fbird_errmsg());
+}
+fbird_close($dbh); // still works - dual-accept
+```
+
+### Transaction Functions
+
+```php
+// v10
+$trans = fbird_trans(IBASE_DEFAULT, $dbh);
+if (!is_resource($trans)) {
+    die('Transaction failed');
+}
+
+// v11
+$trans = fbird_trans(IBASE_DEFAULT, $dbh);
+if ($trans === false) {
+    die('Transaction failed');
+}
+// $trans is now Firebird\Transaction
+```
+
+### Query and Result Functions
+
+```php
+// v10
+$result = fbird_query($dbh, 'SELECT * FROM users');
+if (!is_resource($result)) {
+    die(fbird_errmsg());
+}
+while ($row = fbird_fetch_assoc($result)) {
+    // ...
+}
+fbird_free_result($result);
+
+// v11
+$result = fbird_query($dbh, 'SELECT * FROM users');
+if ($result === false) {
+    die(fbird_errmsg());
+}
+while ($row = fbird_fetch_assoc($result)) {  // dual-accept
+    // ...
+}
+fbird_free_result($result);  // dual-accept
+```
+
+### Blob Functions
+
+```php
+// v10
+$blob = fbird_blob_create($dbh);
+if (!is_resource($blob)) {
+    die('Blob creation failed');
+}
+
+// v11
+$blob = fbird_blob_create($dbh);
+if ($blob === false) {
+    die('Blob creation failed');
+}
+// $blob is now Firebird\Blob
+```
+
+### Event Functions
+
+```php
+// v10
+$event = fbird_set_event_handler($dbh, 'my_callback', 'MY_EVENT');
+if (!is_resource($event)) {
+    die('Event handler failed');
+}
+
+// v11
+$event = fbird_set_event_handler($dbh, 'my_callback', 'MY_EVENT');
+if ($event === false) {
+    die('Event handler failed');
+}
+// $event is now Firebird\Event
+```
+
+### Service Functions
+
+```php
+// v10
+$svc = fbird_service_attach('localhost', 'SYSDBA', 'masterkey');
+if (!is_resource($svc)) {
+    die('Service attach failed');
+}
+
+// v11
+$svc = fbird_service_attach('localhost', 'SYSDBA', 'masterkey');
+if ($svc === false) {
+    die('Service attach failed');
+}
+// $svc is now Firebird\Service
+```
+
+## Checking Object Types
+
+| v10 pattern | v11 equivalent |
+|-------------|----------------|
+| `is_resource($dbh)` | `$dbh instanceof \Firebird\Connection` |
+| `is_resource($trans)` | `$trans instanceof \Firebird\Transaction` |
+| `is_resource($result)` | `$result instanceof \Firebird\ResultSet` |
+| `is_resource($blob)` | `$blob instanceof \Firebird\Blob` |
+| `is_resource($event)` | `$event instanceof \Firebird\Event` |
+| `is_resource($svc)` | `$svc instanceof \Firebird\Service` |
+
+## OOP API (Unchanged)
+
+The `Firebird\Connection`, `Firebird\Database`, `Firebird\Transaction` OOP wrapper
+classes introduced in v10.0 are unchanged. They continue to work as before.
+
+## Dual-Accept Transition Period
+
+All consuming functions accept both legacy `resource` handles and new `Firebird\*`
+objects. This means you can migrate incrementally:
+
+1. Update `is_resource()` checks to `!== false` or `instanceof` checks
+2. Update PHPDoc `@param`/`@return` annotations
+3. Update static analysis stubs (add `satwareag/php-firebird-stubs` as dev dependency)
+
+## Static Analysis
+
+Install the stubs package for PHPStan/Psalm type coverage:
+
+```bash
+composer require --dev satwareag/php-firebird-stubs
+```
+
+Add to `phpstan.neon`:
+
+```yaml
+parameters:
+    stubFiles:
+        - vendor/satwareag/php-firebird-stubs/firebird-stubs.php
+        - vendor/satwareag/php-firebird-stubs/firebird-classes.php
+```
+
+## Summary
+
+The minimum migration effort is:
+1. Replace `is_resource($handle)` with `$handle !== false` throughout your codebase
+2. Ensure PHP 8.2+ is available
+
+No other code changes are required for basic functionality - all consuming functions
+accept both old resources and new objects through dual-accept bridges.

specs/spec-v11-modernization.md

@@ -6,7 +6,7 @@ tags: [modernization, arginfo, resource-to-object, breaking-change, v11]
 priority: 11
 ---
 
-> **Status: IN PROGRESS** - Milestone v11.0 | M3 Phase G complete (2026-04-08)
+> **Status: COMPLETE** - All code criteria met (2026-04-09). Migration guide published (docs/MIGRATION-v10-to-v11.md).
 
 # Spec: v11.0 Modernization
 
@@ -19,7 +19,7 @@ This is a **breaking change** release.
 ## Success Criteria
 
 - [x] M2: All 84 procedural arginfo declarations use typed return macros (CLOSED #175)
-- [ ] M3: Resource-to-object migration - procedural API returns `Firebird\*` objects (IN PROGRESS #176)
+- [x] M3: Resource-to-object migration - procedural API returns `Firebird\*` objects (CLOSED #176, PR #215)
   - [x] Phase A+B: Class skeletons (Connection, Transaction, Event, Batch)
   - [x] Phase C: `fbird_connect/pconnect/create_database` return `Firebird\Connection`
   - [x] Phase D: `fbird_trans/trans_start` return `Firebird\Transaction`
@@ -32,7 +32,7 @@ This is a **breaking change** release.
 - [x] M12: OOP layer uses direct C calls (no `call_user_function`) (CLOSED #177)
 - [x] L3: All dead `FB_API_VER < 30` code paths removed (CLOSED #178)
 - [x] L2: `gds32_ms` fallback removed from `config.w32` (CLOSED #179)
-- [ ] Migration guide for v10.x to v11.0
+- [x] Migration guide for v10.x to v11.0 (docs/MIGRATION-v10-to-v11.md, closed #216)
 - [x] All stubs updated for new return types (Connection, Transaction, ResultSet, Blob done)
 
 ## Part 1: M2 - Arginfo Typed Returns

stubs/composer.json

@@ -36,7 +36,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-satware-main": "10.6.x-dev"
+            "dev-satware-main": "11.0.x-dev"
         }
     }
 }