1 package Catalyst::IOC::Container;
5 use Data::Visitor::Callback;
6 use Catalyst::Utils ();
7 use List::Util qw(first);
8 use Devel::InnerPackage ();
9 use Hash::Util qw/lock_hash/;
10 use MooseX::Types::LoadableClass qw/ LoadableClass /;
12 use Catalyst::IOC::BlockInjection;
13 use Catalyst::IOC::ConstructorInjection;
14 use Module::Pluggable::Object ();
15 use namespace::autoclean;
17 extends 'Bread::Board::Container';
19 has config_local_suffix => (
28 default => sub { +{} },
37 has substitutions => (
40 default => sub { +{} },
43 has application_name => (
49 has sub_container_class => (
53 default => 'Catalyst::IOC::SubContainer',
55 new_sub_container => 'new',
60 my ( $self, $params ) = @_;
63 $self->${\"build_${_}_service"}
84 my $config = $self->resolve( service => 'config' );
86 # don't force default_component to be undef if the config wasn't set
87 my @default_view = $config->{default_view}
88 ? ( default_component => $config->{default_view} )
91 my @default_model = $config->{default_model}
92 ? ( default_component => $config->{default_model} )
96 $self->add_sub_container(
97 $self->build_component_subcontainer
100 $self->add_sub_container(
101 $self->build_controller_subcontainer
104 $self->add_sub_container(
105 $self->build_view_subcontainer( @default_view )
108 $self->add_sub_container(
109 $self->build_model_subcontainer( @default_model )
113 sub build_model_subcontainer {
116 return $self->new_sub_container( @_,
121 sub build_view_subcontainer {
124 return $self->new_sub_container( @_,
129 sub build_controller_subcontainer {
132 return $self->new_sub_container(
133 name => 'controller',
137 sub build_component_subcontainer {
140 return Bread::Board::Container->new(
145 sub build_application_name_service {
148 return Bread::Board::Literal->new( name => 'application_name', value => $self->application_name );
151 sub build_driver_service {
154 return Bread::Board::Literal->new( name => 'driver', value => $self->driver );
157 sub build_file_service {
160 return Bread::Board::Literal->new( name => 'file', value => $self->file );
163 sub build_substitutions_service {
166 return Bread::Board::Literal->new( name => 'substitutions', value => $self->substitutions );
169 sub build_extensions_service {
172 return Bread::Board::BlockInjection->new(
173 lifecycle => 'Singleton',
174 name => 'extensions',
176 return \@{Config::Any->extensions};
181 sub build_prefix_service {
184 return Bread::Board::BlockInjection->new(
185 lifecycle => 'Singleton',
188 return Catalyst::Utils::appprefix( shift->param('application_name') );
190 dependencies => [ depends_on('application_name') ],
194 sub build_path_service {
197 return Bread::Board::BlockInjection->new(
198 lifecycle => 'Singleton',
203 return Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG' )
205 || $s->param('application_name')->path_to( $s->param('prefix') );
207 dependencies => [ depends_on('file'), depends_on('application_name'), depends_on('prefix') ],
211 sub build_config_service {
214 return Bread::Board::BlockInjection->new(
215 lifecycle => 'Singleton',
220 my $v = Data::Visitor::Callback->new(
222 return unless defined $_;
223 return $self->_config_substitutions( $s->param('application_name'), $s->param('substitutions'), $_ );
227 $v->visit( $s->param('raw_config') );
229 dependencies => [ depends_on('application_name'), depends_on('raw_config'), depends_on('substitutions') ],
233 sub build_raw_config_service {
236 return Bread::Board::BlockInjection->new(
237 lifecycle => 'Singleton',
238 name => 'raw_config',
242 my @global = @{$s->param('global_config')};
243 my @locals = @{$s->param('local_config')};
245 my $config = $s->param('class_config');
247 for my $cfg (@global, @locals) {
249 $config = Catalyst::Utils::merge_hashes( $config, $cfg->{$_} );
255 dependencies => [ depends_on('global_config'), depends_on('local_config'), depends_on('class_config') ],
259 sub build_global_files_service {
262 return Bread::Board::BlockInjection->new(
263 lifecycle => 'Singleton',
264 name => 'global_files',
268 my ( $path, $extension ) = @{$s->param('config_path')};
270 my @extensions = @{$s->param('extensions')};
274 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
277 @files = map { "$path.$_" } @extensions;
281 dependencies => [ depends_on('extensions'), depends_on('config_path') ],
285 sub build_local_files_service {
288 return Bread::Board::BlockInjection->new(
289 lifecycle => 'Singleton',
290 name => 'local_files',
294 my ( $path, $extension ) = @{$s->param('config_path')};
295 my $suffix = $s->param('config_local_suffix');
297 my @extensions = @{$s->param('extensions')};
301 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
302 $path =~ s{\.$extension}{_$suffix.$extension};
305 @files = map { "${path}_${suffix}.$_" } @extensions;
309 dependencies => [ depends_on('extensions'), depends_on('config_path'), depends_on('config_local_suffix') ],
313 sub build_class_config_service {
316 return Bread::Board::BlockInjection->new(
317 lifecycle => 'Singleton',
318 name => 'class_config',
321 my $app = $s->param('application_name');
323 # Container might be called outside Catalyst context
324 return {} unless Class::MOP::is_class_loaded($app);
326 # config might not have been defined
327 return $app->config || {};
329 dependencies => [ depends_on('application_name') ],
333 sub build_global_config_service {
336 return Bread::Board::BlockInjection->new(
337 lifecycle => 'Singleton',
338 name => 'global_config',
342 return Config::Any->load_files({
343 files => $s->param('global_files'),
344 filter => \&_fix_syntax,
346 driver_args => $s->param('driver'),
349 dependencies => [ depends_on('global_files') ],
353 sub build_local_config_service {
356 return Bread::Board::BlockInjection->new(
357 lifecycle => 'Singleton',
358 name => 'local_config',
362 return Config::Any->load_files({
363 files => $s->param('local_files'),
364 filter => \&_fix_syntax,
366 driver_args => $s->param('driver'),
369 dependencies => [ depends_on('local_files') ],
373 sub build_config_path_service {
376 return Bread::Board::BlockInjection->new(
377 lifecycle => 'Singleton',
378 name => 'config_path',
382 my $path = $s->param('path');
383 my $prefix = $s->param('prefix');
385 my ( $extension ) = ( $path =~ m{\.(.{1,4})$} );
388 $path =~ s{[\/\\]$}{};
392 return [ $path, $extension ];
394 dependencies => [ depends_on('prefix'), depends_on('path') ],
398 sub build_config_local_suffix_service {
401 return Bread::Board::BlockInjection->new(
402 lifecycle => 'Singleton',
403 name => 'config_local_suffix',
406 my $suffix = Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG_LOCAL_SUFFIX' ) || $self->config_local_suffix;
410 dependencies => [ depends_on('application_name') ],
414 sub build_locate_components_service {
417 return Bread::Board::BlockInjection->new(
418 lifecycle => 'Singleton',
419 name => 'locate_components',
422 my $class = $s->param('application_name');
423 my $config = $s->param('config')->{ setup_components };
425 Catalyst::Exception->throw(
426 qq{You are using search_extra config option. That option is\n} .
427 qq{deprecated, please refer to the documentation for\n} .
428 qq{other ways of achieving the same results.\n}
429 ) if delete $config->{ search_extra };
431 my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
433 my $locator = Module::Pluggable::Object->new(
434 search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
438 return [ $locator->plugins ];
440 dependencies => [ depends_on('application_name'), depends_on('config') ],
444 sub setup_components {
446 warn("Setting up default components");
447 my $class = $self->resolve( service => 'application_name' );
448 my @comps = @{ $self->resolve( service => 'locate_components' ) };
449 my %comps = map { $_ => 1 } @comps;
450 my $deprecatedcatalyst_component_names = 0;
452 for my $component ( @comps ) {
454 # We pass ignore_loaded here so that overlay files for (e.g.)
455 # Model::DBI::Schema sub-classes are loaded - if it's in @comps
456 # we know M::P::O found a file on disk so this is safe
458 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
461 for my $component (@comps) {
462 $self->add_component( $component );
463 # FIXME - $instance->expand_modules() is broken
464 my @expanded_components = $self->expand_component_module( $component );
467 !$deprecatedcatalyst_component_names &&
468 ($deprecatedcatalyst_component_names = $component =~ m/::[CMV]::/) ||
469 ($deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @expanded_components)
471 # FIXME - should I be calling warn here?
472 # Maybe it's time to remove it, or become fatal
473 $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
474 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
478 for my $component (@expanded_components) {
479 $self->add_component( $component )
480 unless $comps{$component};
489 prefix => $_ eq 'Component' ? '' : $_ . '::',
490 values => delete $config->{ lc $_ } || delete $config->{ $_ }
492 grep { ref $config->{ lc $_ } || ref $config->{ $_ } }
493 qw( Component Model M View V Controller C Plugin )
496 foreach my $comp ( @components ) {
497 my $prefix = $comp->{ prefix };
498 foreach my $element ( keys %{ $comp->{ values } } ) {
499 $config->{ "$prefix$element" } = $comp->{ values }->{ $element };
504 sub _config_substitutions {
505 my ( $self, $name, $subs, $arg ) = @_;
507 $subs->{ HOME } ||= sub { shift->path_to( '' ); };
511 if (! defined($ENV{$v})) {
512 Catalyst::Exception->throw( message =>
513 "Missing environment variable: $v" );
519 $subs->{ path_to } ||= sub { shift->path_to( @_ ); };
520 $subs->{ literal } ||= sub { return $_[ 1 ]; };
521 my $subsre = join( '|', keys %$subs );
523 $arg =~ s{__($subsre)(?:\((.+?)\))?__}{ $subs->{ $1 }->( $name, $2 ? split( /,/, $2 ) : () ) }eg;
527 sub get_component_from_sub_container {
528 my ( $self, $sub_container_name, $name, $c, @args ) = @_;
530 my $sub_container = $self->get_sub_container( $sub_container_name );
533 my $default = $sub_container->default_component;
535 return $sub_container->get_component( $default, $c, @args )
536 if $default && $sub_container->has_service( $default );
538 # FIXME - should I be calling $c->log->warn here?
539 # this is never a controller, so this is safe
540 $c->log->warn( "Calling \$c->$sub_container_name() is not supported unless you specify one of:" );
541 $c->log->warn( "* \$c->config(default_$sub_container_name => 'the name of the default $sub_container_name to use')" );
542 $c->log->warn( "* \$c->stash->{current_$sub_container_name} # the name of the view to use for this request" );
543 $c->log->warn( "* \$c->stash->{current_${sub_container_name}_instance} # the instance of the $sub_container_name to use for this request" );
548 return $sub_container->get_component_regexp( $name, $c, @args )
551 return $sub_container->get_component( $name, $c, @args )
552 if $sub_container->has_service( $name );
555 "Attempted to use $sub_container_name '$name', " .
556 "but it does not exist"
563 my ( $self, $component, @args ) = @_;
564 my ( $type, $name ) = _get_component_type_name($component);
567 return $self->get_component_from_sub_container(
571 my $query = ref $component
576 for my $subcontainer_name (qw/model view controller/) {
577 my $subcontainer = $self->get_sub_container( $subcontainer_name );
578 my @components = $subcontainer->get_service_list;
579 @result = grep { m{$component} } @components;
581 return map { $subcontainer->get_component( $_, @args ) } @result
585 # one last search for things like $c->comp(qr/::M::/)
586 @result = $self->_find_component_regexp(
588 ) if !@result and ref $component;
590 # it expects an empty list on failed searches
594 sub _find_component_regexp {
595 my ( $self, $component, @args ) = @_;
598 my @components = grep { m{$component} } keys %{ $self->get_all_components };
601 my ($type, $name) = _get_component_type_name($_);
603 push @result, $self->get_component_from_sub_container(
611 sub get_all_components {
615 # FIXME - if we're getting from these containers, we need to either:
616 # - pass 'ctx' and 'accept_context_args' OR
617 # - make these params optional
618 foreach my $type (qw/model view controller /) {
619 my $container = $self->get_sub_container($type);
621 for my $component ($container->get_service_list) {
622 my $comp = $container->resolve(
623 service => $component
625 my $comp_name = ref $comp || $comp; # THIS IS WRONG! :)
626 # Just as it is called Model::Foo
627 # does not mean it has to be
628 # an instance of model::foo
630 # t0m, you're absolutely right, I really hadn't thought about it.
631 # But then, we have a problem: suppose there is a component called
632 # MyApp::M::Foo, for instance. The service name would be 'Foo',
633 # and it would be stored in the 'model' sub container. So we have
634 # $app_name . '::' . uc_first($type) . '::' . $service_name
635 # that would return MyApp::Model::Foo. It would get really, really
636 # ugly to check MyApp::M::Foo. So, either we change the hash key,
637 # or we drop support for ::[CMV]::, or I don't know, maybe you
638 # have a better solution? :)
640 $components{$comp_name} = $comp;
644 return lock_hash %components;
648 my ( $self, $component ) = @_;
649 my ( $type, $name ) = _get_component_type_name($component);
653 my $component_service_name = "${type}_${name}";
655 # The 'component' sub-container will create the object, and store it's
656 # instance, which, by default, will live throughout the application.
657 # The model/view/controller sub-containers only reference the instance
658 # held in the aforementioned sub-container, and execute the ACCEPT_CONTEXT
659 # sub every time they are called, when it exists.
660 my $instance_container = $self->get_sub_container('component');
661 my $accept_context_container = $self->get_sub_container($type);
663 $instance_container->add_service(
664 Catalyst::IOC::ConstructorInjection->new(
665 name => $component_service_name,
666 catalyst_component_name => $component,
668 lifecycle => 'Singleton',
670 depends_on( '/application_name' ),
673 ) unless $instance_container->has_service( $component_service_name );
674 # ^ custom containers might have added the service already.
675 # we don't want to override that.
677 $accept_context_container->add_service(
678 Catalyst::IOC::BlockInjection->new(
681 depends_on( "/component/$component_service_name" ),
683 block => sub { shift->param($component_service_name) },
685 ) unless $accept_context_container->has_service( $name );
689 # FIXME: should this sub exist?
690 # should it be moved to Catalyst::Utils,
691 # or replaced by something already existing there?
692 sub _get_component_type_name {
693 my ( $component ) = @_;
696 while ( !$result and (my $index = index $component, '::') > 0 ) {
697 my $type = lc substr $component, 0, $index;
698 $component = substr $component, $index + 2;
699 $result = first { $type eq $_ or $type eq substr($_, 0, 1) }
700 qw{ model view controller };
703 return ($result, $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.
750 =head1 Building Services
752 =head2 build_application_name_service
754 Name of the application (such as MyApp).
756 =head2 build_driver_service
758 Config options passed directly to the driver being used.
760 =head2 build_file_service
764 =head2 build_substitutions_service
766 This method substitutes macros found with calls to a function. There are a
767 number of default macros:
771 =item * C<__HOME__> - replaced with C<$c-E<gt>path_to('')>
773 =item * C<__ENV(foo)__> - replaced with the value of C<$ENV{foo}>
775 =item * C<__path_to(foo/bar)__> - replaced with C<$c-E<gt>path_to('foo/bar')>
777 =item * C<__literal(__FOO__)__> - leaves __FOO__ alone (allows you to use
778 C<__DATA__> as a config value, for example)
782 The parameter list is split on comma (C<,>). You can override this method to
783 do your own string munging, or you can define your own macros in
784 C<< <MyApp->config( 'Plugin::ConfigLoader' => { substitutions => { ... } } ) >>.
787 MyApp->config( 'Plugin::ConfigLoader' => {
789 baz => sub { my $c = shift; qux( @_ ); },
793 The above will respond to C<__baz(x,y)__> in config strings.
795 =head2 build_extensions_service
797 Config::Any's available config file extensions (e.g. xml, json, pl, etc).
799 =head2 build_prefix_service
801 The prefix, based on the application name, that will be used to lookup the
802 config files (which will be in the format $prefix.$extension). If the app is
803 MyApp::Foo, the prefix will be myapp_foo.
805 =head2 build_path_service
807 The path to the config file (or environment variable, if defined).
809 =head2 build_config_service
811 The resulting configuration for the application, after it has successfully
812 been loaded, and all substitutions have been made.
814 =head2 build_raw_config_service
816 The merge of local_config and global_config hashes, before substitutions.
818 =head2 build_global_files_service
820 Gets all files for config that don't have the local_suffix, such as myapp.conf.
822 =head2 build_local_files_service
824 Gets all files for config that have the local_suffix, such as myapp_local.conf.
826 =head2 build_global_config_service
828 Reads config from global_files.
830 =head2 build_local_config_service
832 Reads config from local_files.
834 =head2 build_class_config_service
836 Reads config set from the application's class attribute config,
837 i.e. MyApp->config( name => 'MyApp', ... )
839 =head2 build_config_path_service
841 Splits the path to the config file, and returns on array ref containing
842 the path to the config file minus the extension in the first position,
843 and the extension in the second.
845 =head2 build_config_local_suffix_service
847 Determines the suffix of files used to override the main config. By default
848 this value is C<local>, which will load C<myapp_local.conf>. The suffix can
849 be specified in the following order of preference:
853 =item * C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }>
855 =item * C<$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }>
859 The first one of these values found replaces the default of C<local> in the
860 name of the local config file to be loaded.
862 For example, if C< $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> is set to C<testing>,
863 ConfigLoader will try and load C<myapp_testing.conf> instead of
866 =head2 build_locate_components_service
868 This method is meant to provide a list of component modules that should be
869 setup for the application. By default, it will use L<Module::Pluggable>.
871 Specify a C<setup_components> config option to pass additional options directly
872 to L<Module::Pluggable>.
876 =head2 get_component_from_sub_container($sub_container, $name, $c, @args)
878 Looks for components in a given subcontainer (such as controller, model or
879 view), and returns the searched component. If $name is undef, it returns the
880 default component (such as default_view, if $sub_container is 'view'). If
881 $name is a regexp, it returns an array of matching components. Otherwise, it
882 looks for the component with name $name.
884 =head2 get_all_components
886 Fetches all the components, in each of the sub_containers model, view and
887 controller, and returns a readonly hash. The keys are the class names, and
888 the values are the blessed objects. This is what is returned by $c->components.
892 Adds a component to the appropriate subcontainer. The subcontainer is guessed
893 by the component name given.
895 =head2 find_component
897 Searches for components in all containers. If $component is the full class
898 name, the subcontainer is guessed, and it gets the searched component in there.
899 Otherwise, it looks for a component with that name in all subcontainers. If
900 $component is a regexp it calls _find_component_regexp and matches all
901 components against that regexp.
903 =head2 expand_component_module
905 Components found by C<locate_components> will be passed to this method, which
906 is expected to return a list of component (package) names to be set up.
908 =head2 setup_components
912 Catalyst Contributors, see Catalyst.pm
916 This library is free software. You can redistribute it and/or modify it under
917 the same terms as Perl itself.