# info > Class::Container

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

## Quick Reference

- `use Class::Container; @ISA = qw(Class::Container)` — make a class a container
- `__PACKAGE__->valid_params( param => {default => 'value'}, ... )` — declare constructor parameters
- `__PACKAGE__->contained_objects( child => 'ChildClass', ... )` — declare contained objects (automatic creation)
- `__PACKAGE__->contained_objects( child => { class => 'ChildClass', delayed => 1 } )` — declare delayed (lazy) contained objects
- `$self->create_delayed_object('child', ...)` — create a delayed object instance
- `$self->delayed_object_params('child', param => value)` — override parameters for future delayed objects
- `__PACKAGE__->decorates()` — declare a decorator relationship (experimental)
- `$self->container()` — get the object that created you (returns undef if not created by Class::Container)

## 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');
  # ... more initialization ...
  return $self;
}
## Options (Methods)

- `new()` — constructor. Inherit or call `SUPER::new(@_)`. Automatically creates contained objects and passes parameters to the correct class.
- `__PACKAGE__->contained_objects(%hash)` — register contained objects. Keys are parameter names, values are default class or hashref with `class` and `delayed` keys.
- `__PACKAGE__->valid_params(%hash)` — declare accepted parameters. Specifications follow `Params::Validate` format (type, default, optional, isa, etc.). Extra keys like `parse` are ignored.
- `$self->create_delayed_object($name, ...)` — create a delayed object. Arguments override previously passed parameters.
- `$self->delayed_object_params($name, [params])` — get/set parameters for future delayed objects of the given name. Without params, returns hashref of current parameters.
- `$self->delayed_object_class($name)` — returns the class that will be used for delayed objects of the given name.
- `__PACKAGE__->decorates()` — declare decorator pattern (experimental). Set `@ISA` to the decorated class, then call this method.
- `$self->validation_spec()` — returns hashref of validation specs for this class only (excluding contained objects).
- `$class->allowed_params(\%args)` — returns hashref of all accepted parameters (including those passed to contained objects). Optionally pass arguments to refine.
- `$self->container()` — returns the object that created this one (via weakref, requires `Scalar::Utils`). Returns undef if not applicable.
- `$object->show_containers()` — returns a string describing the containment tree (debugging aid).
- `$object->dump_parameters()` — returns a hashref of parameters sufficient to recreate the object. Override for fudging.

## Examples

**Basic container with automatic and delayed objects**

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');
  return $self;
}
**Creating a parent object with parameters for all nested objects**

perl
my $car = Car->new(
  paint => 'red',
  style => 'sedan',
  windshield_class => 'Glass::Laminated',  # overrides default
  radio_class => 'Audio::WMA',
  radio_volume => 5,                       # passed to radio
  wheel_tread => 'all-season',            # passed to wheel (delayed)
);
## See Also

- [Params::Validate](https://www.chedong.com/phpMan.php/perldoc/Params%3A%3AValidate/markdown) — used internally for parameter validation