/ 
Dancer2-Plugin-QuickORM-1.0000
/ README.mkdn

NAME

Dancer2::Plugin::QuickORM - Adds QuickORM syntactic sugar to Dancer2

VERSION

version 1.0000

SYNOPSIS

package MyApp;
use Dancer2;
use Dancer2::Plugin::QuickORM;

set plugins => {
   QuickORM => {
      default => {
         class => 'MyApp::ORM',
      },
   },
};

# 'widget' table -> singular/plural keywords widget()/widgets()
get '/widget/:id' => sub {
   return widget( route_parameters->get('id') );
};

get '/widgets' => sub {
   return [ widgets( { color => 'blue' } ) ];
};

# get at the raw ORM connection directly
get '/stats' => sub {
   return { row_count => orm()->handle('widget')->all };
};

DESCRIPTION

Dancer2::Plugin::QuickORM looks at the ORM(s) you've configured with DBIx::QuickORM, walks every table in their schema(s), and generates a Dancer2 keyword (i.e. an importable function) for each one, so routes can query it without any boilerplate.

For each configured ORM name (see "CONFIGURATION AND ENVIRONMENT"), the plugin's BUILD step:

  1. Loads the configured class and calls $class->orm($name) to obtain a connection.
  2. Iterates $orm->schema($name)->tables and, for each table, derives a singular and a plural keyword name from the table name (splitting StudlyCaps/CamelCase into words and singularising/pluralising with Lingua::EN::Inflect::Phrase).
  3. Registers those keywords, plus schema-prefixed variants (<name>_<singular> and <name>_<plural>), so a table is always reachable unambiguously even if more than one configured ORM exposes a table of the same name.

Generated keywords

If a table's singular and plural forms differ (the common case, e.g. widget/widgets), two keywords are generated:

If a table's singular and plural forms are identical (e.g. moose), a single "smart" keyword is generated instead, which inspects the shape of its argument to decide what you meant:

Keyword collisions

Two different kinds of collision are handled, and handled differently:

SUBROUTINES/METHODS

orm

orm();          # the connection configured as 'default'
orm($name);     # the connection configured under $name

Returns the raw ORM connection object for the given configured name (defaults to 'default' when no name is given). Croaks if $name was not configured.

This is the one keyword the plugin always registers itself (via plugin_keywords), regardless of what tables are configured; use it when you need something the generated per-table keywords don't cover.

BUILD

Runs once when the plugin is instantiated. Reads the plugin configuration, loads each configured ORM class, and generates the per-table keywords described in "DESCRIPTION". Not intended to be called directly.

ATTRIBUTES

This plugin exposes no public attributes of its own. All of its behaviour is driven by the plugins->QuickORM section of your Dancer2 configuration; see "CONFIGURATION AND ENVIRONMENT".

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

Configure one or more named ORMs under plugins->QuickORM in your Dancer2 config:

plugins:
  QuickORM:
    default:
      class: MyApp::ORM
      dsn: "dbi:Pg:dbname=myapp"
    reporting:
      class: MyApp::ORM
      dsn: "dbi:Pg:dbname=myapp_reporting"

Each key under QuickORM is an ORM name (default is used when orm() is called without an argument); each value is a hashref that must contain a class, plus whatever other keys your ORM class needs.

Every key/value pair in a given ORM's configuration (including class itself) is also copied into %ENV as QuickORM_<name>_<key>, and the name itself is set as QuickORM_<name>_name, so the ORM class's orm() constructor can pick up its configuration from the environment if it prefers that to being passed arguments directly.

The configured class must implement the following DBIx::QuickORM features:

$class->orm($name)                     # -> connection object
$orm->schema($name)->tables            # -> list of table objects
$table->name                           # -> table name string
$orm->handle($table_name)              # -> handle object
$handle->by_id($id)                    # -> single row (hashref) or undef
$handle->where($hashref)->all          # -> list of matching rows
$handle->all                           # -> list of every row

DEPENDENCIES

BUGS AND LIMITATIONS

Table names that singularise/pluralise to the same word as a Dancer2 core DSL keyword or another already-registered keyword are only reachable via their schema-prefixed keyword; see "Keyword collisions".

For tables whose singular and plural forms are identical, an arrayref argument is treated as a primary key value (passed straight through to the backend) rather than being rejected outright, since it isn't a hashref and isn't some other clearly-invalid reference type; whether that's a meaningful primary key value is left to the configured ORM class.

Please report any bugs or feature requests through the issue tracker for this distribution.

SEE ALSO

Dancer2, Dancer2::Plugin, DBIx::QuickORM

AUTHOR

D Ruth Holloway ruth@hiruthie.me

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by D Ruth Holloway.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

POD ERRORS

Hey! The above document had some coding errors, which are explained below: