Phalcon Paginator QueryBuilder adapter transition from v3 to v4

The direct answer

The adapter itself did not disappear in Phalcon 4 — it still lives at Phalcon\Paginator\Adapter\QueryBuilder and still expects the same three options: builder (a Phalcon\Mvc\Model\Query\Builder instance), limit, and page. What changed is how you obtain it. Instead of instantiating the adapter class directly as you did in v3, the v4 pattern routes construction through a factory pair:

use Phalcon\Paginator\PaginatorFactory;
use Phalcon\Paginator\AdapterFactory;

$factory   = new PaginatorFactory(new AdapterFactory());
$paginator = $factory->newInstance('queryBuilder', [
    'builder' => $builder,
    'limit'   => 25,
    'page'    => $currentPage,
]);
$page = $paginator->paginate();

Result object access

The second migration trap is the result object. In v3, code commonly read properties such as $page->items or $page->total_pages directly. In v4 the result exposes accessors such as getItems(), getCurrent(), getNext(), getPrevious(), getTotalItems() and getTotalPages(). The exact mix of magic properties versus methods has varied between minor v4 releases, so treat this as a verify-on-your-version item rather than a fixed rule:

$page = $paginator->paginate();
var_dump(get_class_methods($page));
var_dump($page);

Two behavioral notes carry over unchanged: the builder is not executed until paginate() is called (so mutating the builder afterwards changes the result), and the adapter requires a Builder instance — a raw PHQL string or an already-executed resultset is not accepted in either version.

Join counts and deep-offset performance

On your two specific questions, separate what is confirmed from what is likely:

• Join-based counts: the adapter derives its total by running a count against the builder you supply. There is no documented v4 change that makes join counting fundamentally smarter than v3 — if your builder joins tables that multiply rows, the count reflects the joined row set, and the usual fix in either version is to add DISTINCT on the primary key or supply a builder structured for counting. Flag this for verification against your installed minor version.
• Offset latency: the paginator emits LIMIT ... OFFSET ..., and the database must still scan and discard the skipped rows. No paginator configuration in v4 removes that cost. The standard mitigation is keyset (cursor) pagination — filter on id > :last_seen_id with an ORDER BY id instead of a page number — which means bypassing the offset-based adapter for those deep queries. Restricting selected columns and indexing the sort/filter columns is the cheaper partial fix if you must keep numbered pages.

Verification before and after migrating

Because Phalcon ships as a C extension, confirm the runtime matches the API you are coding against:

php -m | grep -i phalcon
php -r 'echo Phalcon\Version::get(), PHP_EOL;'

Then validate behavior with a small script: build the paginator through the factory, call paginate(), and compare getTotalItems() against a hand-written COUNT query over the same join conditions. If those disagree, the problem is in your builder's join/grouping, not in the migration.

One missing detail would sharpen this answer: your exact v4 minor version (e.g. 4.1.x vs 5.x), since result-object accessors and factory signatures shifted between releases.