br-resource-cpt

Name: br-resource-cpt
Author: Lonsdale201

21stars1forks

How to install br-resource-cpt?

lonsdale201/wp-agent-skills/br-resource-cpt

$npx -y skills add Lonsdale201/wp-agent-skills --skill br-resource-cpt

Installs into the current project.

Summary

Build better-route 1.1 CRUD endpoints over a WordPress custom post type with Resource::make, restNamespace, sourceCpt, allow, fields, filters, sort, filterSchema, writeSchema, policy, fieldPolicy, cptVisibleStatuses, cptVisibilityPolicy, pagination, deleteMode, uniformEnvelope, o

Files · 1

View on GitHub

SKILL.md

1	# better-route: CPT Resource CRUD
2
3	Register the Resource itself during `rest_api_init`; it creates and registers its own internal Router from `restNamespace`.
4
5	```php
6	use BetterRoute\Resource\Resource;
7	use BetterRoute\Resource\ResourcePolicy;
8
9	add_action('rest_api_init', static function (): void {
10	Resource::make('books')
11	->restNamespace('myapp/v1')
12	->sourceCpt('book')
13	->allow(['list', 'get', 'create', 'update', 'delete'])
14	->fields(['id', 'title', 'slug', 'content', 'status', 'author'])
15	->filters(['status', 'author'])
16	->filterSchema([
17	'status' => ['type' => 'enum', 'values' => ['publish', 'draft']],
18	'author' => 'int',
19	])
20	->sort(['date', 'title', 'id'])
21	->policy(ResourcePolicy::publicReadPrivateWrite('edit_posts'))
22	->writeSchema([
23	'title' => ['type' => 'string', 'required' => true, 'sanitize' => 'text'],
24	'status' => ['type' => 'enum', 'values' => ['draft', 'publish']],
25	])
26	->deleteMode('trash')
27	->register();
28	});
29	```
30
31	Do not pass a `Router` to `Resource::register()`. Its optional argument is a `DispatcherInterface`, intended mainly for tests/custom dispatch.
32
33	## Actions
34
35	Omitting `allow()` registers full CRUD. In 1.1:
36
37	- `allow(['list', 'get'])` creates a read-only Resource;
38	- `allow([])` deliberately registers no routes;
39	- unsupported names throw `InvalidArgumentException`;
40	- `update` covers both PUT and PATCH.
41
42	Never configure both `sourceCpt()` and `sourceTable()`; the second call now throws.
43
44	## CPT visibility
45
46	Default visible statuses are `['publish']`. Configure the source-verified method:
47
48	```php
49	->cptVisibleStatuses(['publish', 'draft'])
50	```
51
52	There is no `allowedStatuses()` method.
53
54	1.1 fails closed on reads:
55
56	- default list/get permission allows an unset policy only when the post type is publicly viewable;
57	- every item must have a visible status;
58	- the post type/item must be publicly queryable;
59	- password-protected items require `can_read === true`;
60	- the Resource always asks the repository for `id`, `status`, `password_protected`, `publicly_queryable`, and `can_read`, even if the client did not request them;
61	- missing security fields from a custom repository deny rather than expose the item.
62
63	Prefer an explicit Resource policy even though public CPT reads have a safe default.
64
65	For additional item logic:
66
67	```php
68	->cptVisibilityPolicy(static function (array $item, string $action): bool {
69	return ($item['tenant_id'] ?? null) === current_tenant_id();
70	})
71	```
72
73	The callback receives the projected repository item plus action (`list` or `get`), not just a status and not the WP request.
74
75	An arbitrary PHP callback cannot be pushed into `WP_Query`. To keep `total`, pages, and page contents truthful, 1.1 scans every matched repository page, applies the callback, then slices the visible set. This can be expensive. On large datasets, implement visibility in a custom query-level repository/filter so the database produces the correct total.
76
77	## Query contract
78
79	List queries use:
80
81	- `fields=a,b,c`
82	- `sort=field` or `sort=-field`
83	- `page` and `per_page`
84	- explicitly listed filters.
85
86	Configure sort field names without a `-` prefix:
87
88	```php
89	->sort(['date', 'title', 'id'])
90	// Client may request ?sort=-date
91	```
92
93	An empty sort configuration uses the defaults `date` and `id`; it is not an open/no-sort state. The repository adds ID as a stable tie-breaker.
94
95	Strict unknown-parameter checks allow WordPress globals `_locale`, `_fields`, `_embed`, `_envelope`, and `_jsonp`. This keeps `wp.apiFetch`'s `_locale=user` compatible while rejecting other unknown input.
96
97	Configure pagination in any fluent order, but the final state must satisfy:
98
99	- `defaultPerPage >= 1`;
100	- `maxPerPage >= 1`;
101	- `defaultPerPage <= maxPerPage`;
102	- `maxOffset >= 0`.
103
104	Exceeding `maxPerPage` or `maxOffset` returns `400 validation_failed`; values are not silently clamped.
105
106	## Writes and policies
107
108	Use flat enum rules:
109
110	```php
111	['type' => 'enum', 'values' => ['draft', 'publish']]
112	```
113
114	Use `br-write-schema` for validation and `br-resource-policy` for action/field authorization. In 1.1 a denied `fieldPolicy` does not silently discard the field: it returns a validation error or `403 forbidden` according to the rule

People who liked this also viewed

6 picks

Type

br-resource-cpt

21stars1forks

View on GitHub

How to install br-resource-cpt?

lonsdale201/wp-agent-skills/br-resource-cpt

$npx -y skills add Lonsdale201/wp-agent-skills --skill br-resource-cpt

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# better-route: CPT Resource CRUD
2
3	Register the Resource itself during `rest_api_init`; it creates and registers its own internal Router from `restNamespace`.
4
5	```php
6	use BetterRoute\Resource\Resource;
7	use BetterRoute\Resource\ResourcePolicy;
8
9	add_action('rest_api_init', static function (): void {
10	Resource::make('books')
11	->restNamespace('myapp/v1')
12	->sourceCpt('book')
13	->allow(['list', 'get', 'create', 'update', 'delete'])
14	->fields(['id', 'title', 'slug', 'content', 'status', 'author'])
15	->filters(['status', 'author'])
16	->filterSchema([
17	'status' => ['type' => 'enum', 'values' => ['publish', 'draft']],
18	'author' => 'int',
19	])
20	->sort(['date', 'title', 'id'])
21	->policy(ResourcePolicy::publicReadPrivateWrite('edit_posts'))
22	->writeSchema([
23	'title' => ['type' => 'string', 'required' => true, 'sanitize' => 'text'],
24	'status' => ['type' => 'enum', 'values' => ['draft', 'publish']],
25	])
26	->deleteMode('trash')
27	->register();
28	});
29	```
30
31	Do not pass a `Router` to `Resource::register()`. Its optional argument is a `DispatcherInterface`, intended mainly for tests/custom dispatch.
32
33	## Actions
34
35	Omitting `allow()` registers full CRUD. In 1.1:
36
37	- `allow(['list', 'get'])` creates a read-only Resource;
38	- `allow([])` deliberately registers no routes;
39	- unsupported names throw `InvalidArgumentException`;
40	- `update` covers both PUT and PATCH.
41
42	Never configure both `sourceCpt()` and `sourceTable()`; the second call now throws.
43
44	## CPT visibility
45
46	Default visible statuses are `['publish']`. Configure the source-verified method:
47
48	```php
49	->cptVisibleStatuses(['publish', 'draft'])
50	```
51
52	There is no `allowedStatuses()` method.
53
54	1.1 fails closed on reads:
55
56	- default list/get permission allows an unset policy only when the post type is publicly viewable;
57	- every item must have a visible status;
58	- the post type/item must be publicly queryable;
59	- password-protected items require `can_read === true`;
60	- the Resource always asks the repository for `id`, `status`, `password_protected`, `publicly_queryable`, and `can_read`, even if the client did not request them;
61	- missing security fields from a custom repository deny rather than expose the item.
62
63	Prefer an explicit Resource policy even though public CPT reads have a safe default.
64
65	For additional item logic:
66
67	```php
68	->cptVisibilityPolicy(static function (array $item, string $action): bool {
69	return ($item['tenant_id'] ?? null) === current_tenant_id();
70	})
71	```
72
73	The callback receives the projected repository item plus action (`list` or `get`), not just a status and not the WP request.
74
75	An arbitrary PHP callback cannot be pushed into `WP_Query`. To keep `total`, pages, and page contents truthful, 1.1 scans every matched repository page, applies the callback, then slices the visible set. This can be expensive. On large datasets, implement visibility in a custom query-level repository/filter so the database produces the correct total.
76
77	## Query contract
78
79	List queries use:
80
81	- `fields=a,b,c`
82	- `sort=field` or `sort=-field`
83	- `page` and `per_page`
84	- explicitly listed filters.
85
86	Configure sort field names without a `-` prefix:
87
88	```php
89	->sort(['date', 'title', 'id'])
90	// Client may request ?sort=-date
91	```
92
93	An empty sort configuration uses the defaults `date` and `id`; it is not an open/no-sort state. The repository adds ID as a stable tie-breaker.
94
95	Strict unknown-parameter checks allow WordPress globals `_locale`, `_fields`, `_embed`, `_envelope`, and `_jsonp`. This keeps `wp.apiFetch`'s `_locale=user` compatible while rejecting other unknown input.
96
97	Configure pagination in any fluent order, but the final state must satisfy:
98
99	- `defaultPerPage >= 1`;
100	- `maxPerPage >= 1`;
101	- `defaultPerPage <= maxPerPage`;
102	- `maxOffset >= 0`.
103
104	Exceeding `maxPerPage` or `maxOffset` returns `400 validation_failed`; values are not silently clamped.
105
106	## Writes and policies
107
108	Use flat enum rules:
109
110	```php
111	['type' => 'enum', 'values' => ['draft', 'publish']]
112	```
113
114	Use `br-write-schema` for validation and `br-resource-policy` for action/field authorization. In 1.1 a denied `fieldPolicy` does not silently discard the field: it returns a validation error or `403 forbidden` according to the rule

People who liked this also viewed

6 picks

Type