Skip to content

docs(web/guides): scope route-model-binding silent-skip aside to binding=true only #3122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wheels-bot wants to merge 1 commit into from
Closed

docs(web/guides): scope route-model-binding silent-skip aside to binding=true only #3122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/3118-route-model-binding-aside-scope.fixed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Corrects the route-model-binding guide: the "silently skips" aside now applies only to convention-derived `binding=true`, where no matching model class is a normal case (health checks, static pages). A new caution under the explicit-name section clarifies that `binding="ModelName"` throws when the named class can't be resolved — a configuration error, not a silent skip.
8 changes: 6 additions & 2 deletions web/sites/guides/src/content/docs/v4-0-0/digging-deeper/route-model-binding.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ mapper()

The singular model name is derived from the controller name: `posts` (controller) → `Post` (model class) → `params.post` (instance key). Binding is skipped for `index`, `new`, and `create` — those actions have no `params.key` to resolve against.

<Aside type="tip">
With `binding=true`, if the convention-derived model class doesn't exist — for example, the resource routes to a controller without a backing model — the dispatcher silently skips binding. Health checks, static pages, and API gateways keep working without extra configuration.
</Aside>

## Global default

If you want binding turned on everywhere without editing each resource, flip the application-wide default in `config/settings.cfm`:
Expand Down Expand Up @@ -104,8 +108,8 @@ mapper()

`binding="BlogPost"` resolves the `BlogPost` model and stores the instance under `params.blogPost` (the lowercase-initial form of the class name). The `binding` argument accepts `true`, `false`, or a simple string — any non-boolean string is treated as the model class to load.

<Aside type="tip">
If the model class doesn't exist (for example, the resource is routing to a controller that doesn't have a backing model), the dispatcher silently skips binding instead of throwing. This keeps non-model resources — health checks, static pages, API gateways — working without extra configuration.
<Aside type="caution">
An explicit model name like `binding="BlogPost"` behaves differently from `binding=true`. If the named class can't be resolved, dispatch throws — a named binding that fails to resolve is a configuration error, not a silent skip. If your app throws on the first request to a resource with a string binding, check the class name and its CFML mapping. (With `binding=true` the convention-derived class is optional — the dispatcher skips binding if no matching class exists.)
</Aside>

## Scope-level binding
Expand Down
Loading