Order phpdoc annotations meaningfully

[LordSimal]

Especially when using https://github.com/dereuromark/cakephp-ide-helper with a bunch of generics flags enabled one can get a quite big phpdoc list added to each table classe like so

/**
 * StaffMembers Model
 *
 * @property \Cake\ORM\Association\HasMany<\AlfredStaffMembers\Model\Table\StaffMembersProjectsTable> $StaffMembersProjects
 * @property \Cake\ORM\Association\HasMany<\AlfredStaffMembers\Model\Table\StaffMembersWorkTimesTable> $StaffMembersWorkTimes
 * @property \Cake\ORM\Association\HasMany<\AlfredStaffMembers\Model\Table\StaffMemberCarChargesTable> $StaffMemberCarCharges
 * @property \Cake\ORM\Association\HasMany<\App\Model\Table\TimesheetUploadsTable> $TimesheetUploads
 * @property \Cake\ORM\Association\HasMany<\App\Model\Table\MenuItemsTable> $MenuItems
 * @property \Cake\ORM\Association\HasMany<\AlfredStaffMembers\Model\Table\StaffMemberTimeEntriesTable> $StaffMemberTimeEntries
 * @property \Cake\ORM\Association\HasMany<\AlfredStaffMembers\Model\Table\StaffMemberVpnClientsTable> $StaffMemberVpnClients
 * @property \Cake\ORM\Association\BelongsToMany<\AlfredStaffMembers\Model\Table\SoftwareKeysTable> $SoftwareKeys
 * @property \Cake\ORM\Table&\Cake\ORM\Association\HasMany $SoftwareKeysStaffMembers
 * @property \Cake\ORM\Association\HasMany<\AlfredDashboard\Model\Table\DashboardZonesTable> $DashboardZones
 * @method \AlfredStaffMembers\Model\Entity\StaffMember newEmptyEntity()
 * @method \AlfredStaffMembers\Model\Entity\StaffMember newEntity(array<mixed> $data, array<string, mixed> $options = [])
 * @method array<\AlfredStaffMembers\Model\Entity\StaffMember> newEntities(array<mixed> $data, array<string, mixed> $options = [])
 * @method \AlfredStaffMembers\Model\Entity\StaffMember get(mixed $primaryKey, array|string $finder = 'all', \Psr\SimpleCache\CacheInterface|string|null $cache = null, \Closure|string|null $cacheKey = null, mixed ...$args)
 * @method \AlfredStaffMembers\Model\Entity\StaffMember findOrCreate(\Cake\ORM\Query\SelectQuery|callable|array $search, ?callable $callback = null, array<string, mixed> $options = [])
 * @method \AlfredStaffMembers\Model\Entity\StaffMember patchEntity(\AlfredStaffMembers\Model\Entity\StaffMember $entity, array<mixed> $data, array<string, mixed> $options = [])
 * @method array<\AlfredStaffMembers\Model\Entity\StaffMember> patchEntities(iterable<\AlfredStaffMembers\Model\Entity\StaffMember> $entities, array<mixed> $data, array<string, mixed> $options = [])
 * @method \AlfredStaffMembers\Model\Entity\StaffMember|false save(\AlfredStaffMembers\Model\Entity\StaffMember $entity, array<string, mixed> $options = [])
 * @method \AlfredStaffMembers\Model\Entity\StaffMember saveOrFail(\AlfredStaffMembers\Model\Entity\StaffMember $entity, array<string, mixed> $options = [])
 * @method \Cake\Datasource\ResultSetInterface<\AlfredStaffMembers\Model\Entity\StaffMember>|false saveMany(iterable<\AlfredStaffMembers\Model\Entity\StaffMember> $entities, array<string, mixed> $options = [])
 * @method \Cake\Datasource\ResultSetInterface<\AlfredStaffMembers\Model\Entity\StaffMember> saveManyOrFail(iterable<\AlfredStaffMembers\Model\Entity\StaffMember> $entities, array<string, mixed> $options = [])
 * @method \Cake\Datasource\ResultSetInterface<\AlfredStaffMembers\Model\Entity\StaffMember>|false deleteMany(iterable<\AlfredStaffMembers\Model\Entity\StaffMember> $entities, array<string, mixed> $options = [])
 * @method \Cake\Datasource\ResultSetInterface<\AlfredStaffMembers\Model\Entity\StaffMember> deleteManyOrFail(iterable<\AlfredStaffMembers\Model\Entity\StaffMember> $entities, array<string, mixed> $options = [])
 * @mixin \Cake\ORM\Behavior\TimestampBehavior
 * @mixin \App\Model\Behavior\SunlimeEncryptionBehavior
 * @extends \Cake\ORM\Table<array{AuditLog: \AuditStash\Model\Behavior\AuditLogBehavior, SunlimeEncryption: \App\Model\Behavior\SunlimeEncryptionBehavior, Timestamp: \Cake\ORM\Behavior\TimestampBehavior}, \AlfredStaffMembers\Model\Entity\StaffMember>
 * @mixin \AuditStash\Model\Behavior\AuditLogBehavior
 * @method bool delete(\AlfredStaffMembers\Model\Entity\StaffMember $entity, array<string, mixed> $options = [])
 * @method bool deleteOrFail(\AlfredStaffMembers\Model\Entity\StaffMember $entity, array<string, mixed> $options = [])
 * @method \AlfredStaffMembers\Model\Entity\StaffMember|array<\AlfredStaffMembers\Model\Entity\StaffMember> loadInto(\AlfredStaffMembers\Model\Entity\StaffMember|array<\AlfredStaffMembers\Model\Entity\StaffMember> $entities, array $contain)
 */
class StaffMembersTable extends Table
{

and as you can see, the ordering is quite out of whack. This should be the concern of the IDE-Helper but instead should be somehow standardized in our CS rules as currently it doesn't complain.

[LordSimal]

in this case I'd say

• properties
• methods
  • with create, read, update, delete order
• mixins
• extends

[dereuromark]

Order I'd argue for:

1. @extends / @implements / @template — these define the class's own type signature (what it is). PHPStan/Psalm convention puts them first, and they're usually one line so they don't bury the rest.
2. @property — associations / structural state (what it has).
3. @method — in CRUD-ish order: new* → get/find* → patch*/save*/findOrCreate → delete*. ORM-flavored variants (*OrFail, *Many, *ManyOrFail) grouped right after their base method, not separately.
4. @mixin — behaviors come last because they're additive/late-bound; the class is already fully described by the time you read them.

Reasoning for @extends first vs. your "extends last": @extends \App\Model\Table\Table<{...behaviors...}> is a declaration about the class itself, whereas @property/@method are describing members. Putting the class-level signature first matches how class Foo extends Bar reads in actual PHP.
Last-position works too if you treat it as "tooling footnote" — but then mixins arguably belong there too, and you end up with a fuzzier rule.

[LordSimal]

I am just used to having the extends at the end but since there is no required order by phpstan/psalm your order is fine by me 👍🏻

[dereuromark]

Maybe two steps for now.

Step 1: Tag type ordering (big win already):

I added it to php-collective/code-sniffer#59 and dogfooded it on sandbox:
dereuromark/cakephp-sandbox#126

Also did:

• Group strict-mode delete methods with their batch variants dereuromark/cakephp-ide-helper#441

Fresh output (bake, ..) is fine already by design.

Step 2: Ordering within (e.g. method)

TBD

For now claude/codex can quickly do this upon request ( dereuromark/cakephp-sandbox@a24a78c ).

For a code sniffer this could almost be a bit ouf of scope. Not sure yet.

[dereuromark]

For Step 2 my idea:
php-collective/code-sniffer#60

Keeping the "opinionated" part fully ouf of it on project side to specify.

[dereuromark]

This is how it would look like incl properties:
dereuromark/cakephp-sandbox#127

IF props are included, one needs to exclude entities etc IMO, as those are the usually ordered by DB order, and that is meaningful (id first, created/modified last, things grouped by relevance).