1 package Catalyst::IOC::Container;
5 use Data::Visitor::Callback;
6 use Catalyst::Utils ();
7 use Devel::InnerPackage ();
8 use Hash::Util qw/lock_hash/;
9 use MooseX::Types::LoadableClass qw/ LoadableClass /;
11 use Catalyst::IOC::BlockInjection;
12 use Catalyst::IOC::ConstructorInjection;
13 use Module::Pluggable::Object ();
14 use namespace::autoclean;
16 extends 'Bread::Board::Container';
18 has config_local_suffix => (
27 default => sub { +{} },
36 has substitutions => (
39 default => sub { +{} },
42 has application_name => (
48 has sub_container_class => (
52 default => 'Catalyst::IOC::SubContainer',
54 new_sub_container => 'new',
59 my ( $self, $params ) = @_;
62 $self->${\"build_${_}_service"}
83 my $config = $self->resolve( service => 'config' );
85 $self->add_sub_container(
86 $self->build_component_subcontainer
89 $self->add_sub_container(
90 $self->build_controller_subcontainer
93 $self->add_sub_container(
94 $self->build_view_subcontainer(
95 default_component => $config->{default_view},
99 $self->add_sub_container(
100 $self->build_model_subcontainer(
101 default_component => $config->{default_model},
106 sub build_model_subcontainer {
109 return $self->new_sub_container( @_,
114 sub build_view_subcontainer {
117 return $self->new_sub_container( @_,
122 sub build_controller_subcontainer {
125 return $self->new_sub_container(
126 name => 'controller',
130 sub build_component_subcontainer {
133 return Bread::Board::Container->new(
138 sub build_application_name_service {
141 return Bread::Board::Literal->new( name => 'application_name', value => $self->application_name );
144 sub build_driver_service {
147 return Bread::Board::Literal->new( name => 'driver', value => $self->driver );
150 sub build_file_service {
153 return Bread::Board::Literal->new( name => 'file', value => $self->file );
156 sub build_substitutions_service {
159 return Bread::Board::Literal->new( name => 'substitutions', value => $self->substitutions );
162 sub build_extensions_service {
165 return Bread::Board::BlockInjection->new(
166 lifecycle => 'Singleton',
167 name => 'extensions',
169 return \@{Config::Any->extensions};
174 sub build_prefix_service {
177 return Bread::Board::BlockInjection->new(
178 lifecycle => 'Singleton',
181 return Catalyst::Utils::appprefix( shift->param('application_name') );
183 dependencies => [ depends_on('application_name') ],
187 sub build_path_service {
190 return Bread::Board::BlockInjection->new(
191 lifecycle => 'Singleton',
196 return Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG' )
198 || $s->param('application_name')->path_to( $s->param('prefix') );
200 dependencies => [ depends_on('file'), depends_on('application_name'), depends_on('prefix') ],
204 sub build_config_service {
207 return Bread::Board::BlockInjection->new(
208 lifecycle => 'Singleton',
213 my $v = Data::Visitor::Callback->new(
215 return unless defined $_;
216 return $self->_config_substitutions( $s->param('application_name'), $s->param('substitutions'), $_ );
220 $v->visit( $s->param('raw_config') );
222 dependencies => [ depends_on('application_name'), depends_on('raw_config'), depends_on('substitutions') ],
226 sub build_raw_config_service {
229 return Bread::Board::BlockInjection->new(
230 lifecycle => 'Singleton',
231 name => 'raw_config',
235 my @global = @{$s->param('global_config')};
236 my @locals = @{$s->param('local_config')};
238 my $config = $s->param('class_config');
240 for my $cfg (@global, @locals) {
242 $config = Catalyst::Utils::merge_hashes( $config, $cfg->{$_} );
248 dependencies => [ depends_on('global_config'), depends_on('local_config'), depends_on('class_config') ],
252 sub build_global_files_service {
255 return Bread::Board::BlockInjection->new(
256 lifecycle => 'Singleton',
257 name => 'global_files',
261 my ( $path, $extension ) = @{$s->param('config_path')};
263 my @extensions = @{$s->param('extensions')};
267 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
270 @files = map { "$path.$_" } @extensions;
274 dependencies => [ depends_on('extensions'), depends_on('config_path') ],
278 sub build_local_files_service {
281 return Bread::Board::BlockInjection->new(
282 lifecycle => 'Singleton',
283 name => 'local_files',
287 my ( $path, $extension ) = @{$s->param('config_path')};
288 my $suffix = $s->param('config_local_suffix');
290 my @extensions = @{$s->param('extensions')};
294 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
295 $path =~ s{\.$extension}{_$suffix.$extension};
298 @files = map { "${path}_${suffix}.$_" } @extensions;
302 dependencies => [ depends_on('extensions'), depends_on('config_path'), depends_on('config_local_suffix') ],
306 sub build_class_config_service {
309 return Bread::Board::BlockInjection->new(
310 lifecycle => 'Singleton',
311 name => 'class_config',
314 my $app = $s->param('application_name');
316 # Container might be called outside Catalyst context
317 return {} unless Class::MOP::is_class_loaded($app);
319 # config might not have been defined
320 return $app->config || {};
322 dependencies => [ depends_on('application_name') ],
326 sub build_global_config_service {
329 return Bread::Board::BlockInjection->new(
330 lifecycle => 'Singleton',
331 name => 'global_config',
335 return Config::Any->load_files({
336 files => $s->param('global_files'),
337 filter => \&_fix_syntax,
339 driver_args => $s->param('driver'),
342 dependencies => [ depends_on('global_files') ],
346 sub build_local_config_service {
349 return Bread::Board::BlockInjection->new(
350 lifecycle => 'Singleton',
351 name => 'local_config',
355 return Config::Any->load_files({
356 files => $s->param('local_files'),
357 filter => \&_fix_syntax,
359 driver_args => $s->param('driver'),
362 dependencies => [ depends_on('local_files') ],
366 sub build_config_path_service {
369 return Bread::Board::BlockInjection->new(
370 lifecycle => 'Singleton',
371 name => 'config_path',
375 my $path = $s->param('path');
376 my $prefix = $s->param('prefix');
378 my ( $extension ) = ( $path =~ m{\.(.{1,4})$} );
381 $path =~ s{[\/\\]$}{};
385 return [ $path, $extension ];
387 dependencies => [ depends_on('prefix'), depends_on('path') ],
391 sub build_config_local_suffix_service {
394 return Bread::Board::BlockInjection->new(
395 lifecycle => 'Singleton',
396 name => 'config_local_suffix',
399 my $suffix = Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG_LOCAL_SUFFIX' ) || $self->config_local_suffix;
403 dependencies => [ depends_on('application_name') ],
407 sub build_locate_components_service {
410 return Bread::Board::BlockInjection->new(
411 lifecycle => 'Singleton',
412 name => 'locate_components',
415 my $class = $s->param('application_name');
416 my $config = $s->param('config')->{ setup_components };
418 Catalyst::Exception->throw(
419 qq{You are using search_extra config option. That option is\n} .
420 qq{deprecated, please refer to the documentation for\n} .
421 qq{other ways of achieving the same results.\n}
422 ) if delete $config->{ search_extra };
424 my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
426 my $locator = Module::Pluggable::Object->new(
427 search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
431 return [ $locator->plugins ];
433 dependencies => [ depends_on('application_name'), depends_on('config') ],
437 sub setup_components {
439 my $class = $self->resolve( service => 'application_name' );
440 my @comps = @{ $self->resolve( service => 'locate_components' ) };
441 my %comps = map { $_ => 1 } @comps;
442 my $deprecatedcatalyst_component_names = 0;
444 for my $component ( @comps ) {
446 # We pass ignore_loaded here so that overlay files for (e.g.)
447 # Model::DBI::Schema sub-classes are loaded - if it's in @comps
448 # we know M::P::O found a file on disk so this is safe
450 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
453 for my $component (@comps) {
454 $self->add_component( $component );
455 # FIXME - $instance->expand_modules() is broken
456 my @expanded_components = $self->expand_component_module( $component );
459 !$deprecatedcatalyst_component_names &&
460 ($deprecatedcatalyst_component_names = $component =~ m/::[CMV]::/) ||
461 ($deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @expanded_components)
463 # FIXME - should I be calling warn here?
464 # Maybe it's time to remove it, or become fatal
465 $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
466 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
470 for my $component (@expanded_components) {
471 $self->add_component( $component )
472 unless $comps{$component};
476 $self->get_sub_container('model')->make_single_default;
477 $self->get_sub_container('view')->make_single_default;
484 prefix => $_ eq 'Component' ? '' : $_ . '::',
485 values => delete $config->{ lc $_ } || delete $config->{ $_ }
487 grep { ref $config->{ lc $_ } || ref $config->{ $_ } }
488 qw( Component Model M View V Controller C Plugin )
491 foreach my $comp ( @components ) {
492 my $prefix = $comp->{ prefix };
493 foreach my $element ( keys %{ $comp->{ values } } ) {
494 $config->{ "$prefix$element" } = $comp->{ values }->{ $element };
499 sub _config_substitutions {
500 my ( $self, $name, $subs, $arg ) = @_;
502 $subs->{ HOME } ||= sub { shift->path_to( '' ); };
506 if (! defined($ENV{$v})) {
507 Catalyst::Exception->throw( message =>
508 "Missing environment variable: $v" );
514 $subs->{ path_to } ||= sub { shift->path_to( @_ ); };
515 $subs->{ literal } ||= sub { return $_[ 1 ]; };
516 my $subsre = join( '|', keys %$subs );
518 $arg =~ s{__($subsre)(?:\((.+?)\))?__}{ $subs->{ $1 }->( $name, $2 ? split( /,/, $2 ) : () ) }eg;
522 sub get_component_from_sub_container {
523 my ( $self, $sub_container_name, $name, $c, @args ) = @_;
525 my $sub_container = $self->get_sub_container( $sub_container_name );
528 my $default = $sub_container->default_component;
530 return $sub_container->get_component( $default, $c, @args )
531 if $default && $sub_container->has_service( $default );
533 # FIXME - should I be calling $c->log->warn here?
534 # this is never a controller, so this is safe
535 $c->log->warn( "Calling \$c->$sub_container_name() is not supported unless you specify one of:" );
536 $c->log->warn( "* \$c->config(default_$sub_container_name => 'the name of the default $sub_container_name to use')" );
537 $c->log->warn( "* \$c->stash->{current_$sub_container_name} # the name of the view to use for this request" );
538 $c->log->warn( "* \$c->stash->{current_${sub_container_name}_instance} # the instance of the $sub_container_name to use for this request" );
543 return $sub_container->get_component_regexp( $name, $c, @args )
546 return $sub_container->get_component( $name, $c, @args )
547 if $sub_container->has_service( $name );
550 "Attempted to use $sub_container_name '$name', " .
551 "but it does not exist"
558 my ( $self, $component, @args ) = @_;
559 my ( $type, $name ) = _get_component_type_name($component);
562 return $self->get_component_from_sub_container(
566 my $query = ref $component
571 for my $subcontainer_name (qw/model view controller/) {
572 my $subcontainer = $self->get_sub_container( $subcontainer_name );
573 my @components = $subcontainer->get_service_list;
574 @result = grep { m{$component} } @components;
576 return map { $subcontainer->get_component( $_, @args ) } @result
580 # one last search for things like $c->comp(qr/::M::/)
581 @result = $self->find_component_regexp(
583 ) if !@result and ref $component;
585 # it expects an empty list on failed searches
589 sub find_component_regexp {
590 my ( $self, $component, @args ) = @_;
593 my @components = grep { m{$component} } keys %{ $self->get_all_components };
596 my ($type, $name) = _get_component_type_name($_);
598 push @result, $self->get_component_from_sub_container(
606 # FIXME - t0m, how do you feel about this name?
607 # also, do you think I should draw it here, or just return the data structure?
608 sub get_components_names_types {
610 my @comps_names_types;
612 for my $sub_container_name (qw/model view controller/) {
613 my $sub_container = $self->get_sub_container($sub_container_name);
614 for my $service ( $sub_container->get_service_list ) {
615 my $comp = $sub_container->resolve(service => $service);
616 my $compname = ref $comp || $comp;
617 my $type = ref $comp ? 'instance' : 'class';
618 push @comps_names_types, [ $compname, $type ];
622 return @comps_names_types;
625 sub get_all_components {
629 my $container = $self->get_sub_container('component');
631 for my $component ($container->get_service_list) {
632 my $comp = $container->resolve(
633 service => $component
635 my $comp_name = ref $comp || $comp;
636 $components{$comp_name} = $comp;
639 return lock_hash %components;
643 my ( $self, $component ) = @_;
644 my ( $type, $name ) = _get_component_type_name($component);
648 my $component_service_name = "${type}_${name}";
650 # The 'component' sub-container will create the object, and store it's
651 # instance, which, by default, will live throughout the application.
652 # The model/view/controller sub-containers only reference the instance
653 # held in the aforementioned sub-container, and execute the ACCEPT_CONTEXT
654 # sub every time they are called, when it exists.
655 my $instance_container = $self->get_sub_container('component');
656 my $accept_context_container = $self->get_sub_container($type);
658 $instance_container->add_service(
659 Catalyst::IOC::ConstructorInjection->new(
660 name => $component_service_name,
662 lifecycle => 'Singleton',
664 depends_on( '/application_name' ),
665 depends_on( '/config' ),
668 ) unless $instance_container->has_service( $component_service_name );
669 # ^ custom containers might have added the service already.
670 # we don't want to override that.
672 $accept_context_container->add_service(
673 Catalyst::IOC::BlockInjection->new(
676 depends_on( "/component/$component_service_name" ),
678 block => sub { shift->param($component_service_name) },
680 ) unless $accept_context_container->has_service( $name );
684 # FIXME: should this sub exist?
685 # should it be moved to Catalyst::Utils,
686 # or replaced by something already existing there?
687 sub _get_component_type_name {
688 my ( $component ) = @_;
690 my @parts = split /::/, $component;
692 while (my $type = shift @parts) {
693 return ('controller', join '::', @parts)
694 if $type =~ /^(c|controller)$/i;
696 return ('model', join '::', @parts)
697 if $type =~ /^(m|model)$/i;
699 return ('view', join '::', @parts)
700 if $type =~ /^(v|view)$/i;
703 return (undef, $component);
706 sub expand_component_module {
707 my ( $class, $module ) = @_;
708 return Devel::InnerPackage::list_packages( $module );
719 Catalyst::Container - IOC for Catalyst components
727 =head1 Building Containers
729 =head2 build_component_subcontainer
731 Container that stores all components, i.e. all models, views and controllers
732 together. Each service is an instance of the actual component, and by default
733 it lives while the application is running. Retrieving components from this
734 subcontainer will instantiate the component, if it hasn't been instantiated
735 already, but will not execute ACCEPT_CONTEXT.
737 =head2 build_model_subcontainer
739 Container that stores references for all models that are inside the components
740 subcontainer. Retrieving a model triggers ACCEPT_CONTEXT, if it exists.
742 =head2 build_view_subcontainer
744 Same as L<build_model_subcontainer>, but for views.
746 =head2 build_controller_subcontainer
748 Same as L<build_model_subcontainer>, but for controllers. The difference is
749 that there is no ACCEPT_CONTEXT for controllers.
751 =head1 Building Services
753 =head2 build_application_name_service
755 Name of the application (such as MyApp).
757 =head2 build_driver_service
759 Config options passed directly to the driver being used.
761 =head2 build_file_service
765 =head2 build_substitutions_service
767 This method substitutes macros found with calls to a function. There are a
768 number of default macros:
772 =item * C<__HOME__> - replaced with C<$c-E<gt>path_to('')>
774 =item * C<__ENV(foo)__> - replaced with the value of C<$ENV{foo}>
776 =item * C<__path_to(foo/bar)__> - replaced with C<$c-E<gt>path_to('foo/bar')>
778 =item * C<__literal(__FOO__)__> - leaves __FOO__ alone (allows you to use
779 C<__DATA__> as a config value, for example)
783 The parameter list is split on comma (C<,>). You can override this method to
784 do your own string munging, or you can define your own macros in
785 C<MyApp-E<gt>config-E<gt>{ 'Plugin::ConfigLoader' }-E<gt>{ substitutions }>.
788 MyApp->config->{ 'Plugin::ConfigLoader' }->{ substitutions } = {
789 baz => sub { my $c = shift; qux( @_ ); }
792 The above will respond to C<__baz(x,y)__> in config strings.
794 =head2 build_extensions_service
796 Config::Any's available config file extensions (e.g. xml, json, pl, etc).
798 =head2 build_prefix_service
800 The prefix, based on the application name, that will be used to lookup the
801 config files (which will be in the format $prefix.$extension). If the app is
802 MyApp::Foo, the prefix will be myapp_foo.
804 =head2 build_path_service
806 The path to the config file (or environment variable, if defined).
808 =head2 build_config_service
810 The resulting configuration for the application, after it has successfully
811 been loaded, and all substitutions have been made.
813 =head2 build_raw_config_service
815 The merge of local_config and global_config hashes, before substitutions.
817 =head2 build_global_files_service
819 Gets all files for config that don't have the local_suffix, such as myapp.conf.
821 =head2 build_local_files_service
823 Gets all files for config that have the local_suffix, such as myapp_local.conf.
825 =head2 build_global_config_service
827 Reads config from global_files.
829 =head2 build_local_config_service
831 Reads config from local_files.
833 =head2 build_class_config_service
835 Reads config set from the application's class attribute config,
836 i.e. MyApp->config( name => 'MyApp', ... )
838 =head2 build_config_path_service
840 Splits the path to the config file, and returns on array ref containing
841 the path to the config file minus the extension in the first position,
842 and the extension in the second.
844 =head2 build_config_local_suffix_service
846 Determines the suffix of files used to override the main config. By default
847 this value is C<local>, which will load C<myapp_local.conf>. The suffix can
848 be specified in the following order of preference:
852 =item * C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }>
854 =item * C<$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }>
858 The first one of these values found replaces the default of C<local> in the
859 name of the local config file to be loaded.
861 For example, if C< $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> is set to C<testing>,
862 ConfigLoader will try and load C<myapp_testing.conf> instead of
865 =head2 build_locate_components_service
867 This method is meant to provide a list of component modules that should be
868 setup for the application. By default, it will use L<Module::Pluggable>.
870 Specify a C<setup_components> config option to pass additional options directly
871 to L<Module::Pluggable>.
875 =head2 get_component_from_sub_container($sub_container, $name, $c, @args)
877 Looks for components in a given subcontainer (such as controller, model or
878 view), and returns the searched component. If $name is undef, it returns the
879 default component (such as default_view, if $sub_container is 'view'). If
880 $name is a regexp, it returns an array of matching components. Otherwise, it
881 looks for the component with name $name.
883 =head2 get_components_names_types
885 Gets all components from all containers and returns them as an array of
886 arrayrefs containing the component name and the component type (i.e., whether
887 it's an instance or a class).
889 =head2 get_all_components
891 Fetches all the components, in each of the sub_containers model, view and
892 controller, and returns a readonly hash. The keys are the class names, and
893 the values are the blessed objects. This is what is returned by $c->components.
897 Adds a component to the appropriate subcontainer. The subcontainer is guessed
898 by the component name given.
900 =head2 find_component
902 Searches for components in all containers. If $component is the full class
903 name, the subcontainer is guessed, and it gets the searched component in there.
904 Otherwise, it looks for a component with that name in all subcontainers. If
905 $component is a regexp, it calls the method below, find_component_regexp,
906 and matches all components against that regexp.
908 =head2 find_component_regexp
910 Finds components that match a given regexp. Used internally, by find_component.
912 =head2 expand_component_module
914 Components found by C<locate_components> will be passed to this method, which
915 is expected to return a list of component (package) names to be set up.
917 =head2 setup_components
921 Catalyst Contributors, see Catalyst.pm
925 This library is free software. You can redistribute it and/or modify it under
926 the same terms as Perl itself.