# man > Class::Container(3pm)

---
type: CommandReference
command: Class::Container
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `use Class::Container; @ISA = qw(Class::Container);` — inherit container behavior.
- `__PACKAGE__->valid_params(paint => {default => 'burgundy'}, radio => {isa => 'Audio::Device'});` — declare accepted constructor parameters.
- `__PACKAGE__->contained_objects(windshield => 'Glass::Shatterproof', wheel => {class => 'Vehicle::Wheel', delayed => 1});` — declare contained objects (auto-created or delayed).
- `my $self = $package->SUPER::new(@_);` — call superclass construction; auto-creates immediate contained objects.
- `$self->create_delayed_object('wheel');` — manually instantiate a delayed contained object.
- `$self->create_delayed_object('foo', extra => 'param');` — pass extra parameters to delayed object.
- `__PACKAGE__->decorates('SomeClass');` — declare this class as a decorator of `SomeClass` (experimental).
- `$object->container()` — returns the object that created this one (or `undef`).

## Name
Class::Container – Glues object frameworks together transparently

## Synopsis
perl
package Car;
use Class::Container;
@ISA = qw(Class::Container);

__PACKAGE__->valid_params(
    paint      => {default => 'burgundy'},
    style      => {default => 'coupe'},
    windshield => {isa => 'Glass'},
    radio      => {isa => 'Audio::Device'},
);

__PACKAGE__->contained_objects(
    windshield => 'Glass::Shatterproof',
    wheel      => {class => 'Vehicle::Wheel', delayed => 1},
    radio      => 'Audio::MP3',
);

sub new {
    my $package = shift;
    my $self = $package->SUPER::new(@_);
    $self->{right_wheel} = $self->create_delayed_object('wheel');
    # … further initialization …
    return $self;
}
## Methods

### Construction
- **`new()`** — Inherited constructor. Handles automatic forwarding of parameters to contained objects. Subclasses should call `$package->SUPER::new(@_)` and then perform additional initialization.

### Class Methods (declarative)
- **`contained_objects()`** — Declares the objects this class creates. Takes a hash mapping slot names to class names or to a hashref with keys `class` (required) and `delayed => 1` (optional). Parameters destined for the contained class are passed through automatically. If the caller supplies a parameter `slot_class`, that subclass is used instead.
- **`valid_params(...)`** — Declares the named parameters this class accepts (specs compatible with [Params::Validate](http://localhost/phpMan.php/perldoc/Params%3A%3AValidate/markdown)). Extra fields in the spec are ignored. Can be reset with `__PACKAGE__->valid_params(undef)`.
- **`decorates()`** — (Experimental) Declares this class as a decorator of another class. The decorated class should be listed in `@ISA`. Simplifies adding mix-in functionality.

### Object Methods
- **`create_delayed_object($name, ...)`** — Instantiates a delayed contained object identified by `$name`. Extra arguments override parameters previously passed to the container constructor. Must be called as an instance method.
- **`delayed_object_params($name)`** — Returns a hashref of the parameters that will be used to create the given delayed object. If called with additional key-value pairs, sets those parameters.
- **`delayed_object_class($name)`** — Returns the class that will be used for the delayed object named `$name`.
- **`container()`** — Returns the object that created this instance (stored via weak reference); `undef` if not created by another container.
- **`show_containers()`** — Returns a string describing the containment hierarchy.
- **`dump_parameters()`** — Returns a hashref of parameters sufficient to recreate the object, based on current state. Subclasses may override to adjust the mapping.

### Accessors
- **`allowed_params(\%args)`** — Class method. Returns a hashref of all parameters accepted by the class, including those passed down to contained objects. If `%args` is provided, it influences the result (e.g., dynamic delegation may change accepted parameters).
- **`validation_spec()`** — Returns a hashref suitable for `Params::Validate::validate()`. Does not include parameters for contained objects.

## Examples
perl
# Basic container class
package Car;
use Class::Container;
@ISA = qw(Class::Container);

__PACKAGE__->valid_params(
    paint      => {default => 'burgundy'},
    style      => {default => 'coupe'},
    windshield => {isa => 'Glass'},
    radio      => {isa => 'Audio::Device'},
);

__PACKAGE__->contained_objects(
    windshield => 'Glass::Shatterproof',
    wheel      => {class => 'Vehicle::Wheel', delayed => 1},
    radio      => 'Audio::MP3',
);

sub new {
    my $package = shift;
    my $self = $package->SUPER::new(@_);
    $self->{right_wheel} = $self->create_delayed_object('wheel');
    return $self;
}

# Creating a Car instance, passing parameters to contained objects
my $car = Car->new(
    paint           => 'blue',
    windshield_class => 'Glass::Tinted',    # use a subclass
    radio_volume    => 11,                  # parameter for the radio
);
## See Also
- [Params::Validate](http://localhost/phpMan.php/perldoc/Params%3A%3AValidate/markdown)