| blob | 700a734b5f7a1f5f1a78846ca683b87afce11f47 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.loader.autoloader">
4 <title>The Autoloader</title>
6 <para>
7 <classname>Zend_Loader_Autoloader</classname> introduces a comprehensive
8 autoloading solution for Zend Framework. It has been designed with
9 several goals in mind:
10 </para>
12 <itemizedlist>
13 <listitem>
14 <para>
15 Provide a true namespace autoloader. (Previous incarnations
16 intercepted all userland namespaces.)
17 </para>
18 </listitem>
20 <listitem>
21 <para>
22 Allow registering arbitrary callbacks as autoloaders, and manage
23 them as a stack. (At the time of this writing, this overcomes some
24 issues with <code>spl_autoload</code>, which does not allow
25 re-registering a callback that utilizes an instance method.)
26 </para>
27 </listitem>
29 <listitem>
30 <para>
31 Allow optimistic matching of namespaces to provide faster class resolution.
32 </para>
33 </listitem>
34 </itemizedlist>
36 <para>
37 <classname>Zend_Loader_Autoloader</classname> implements a singleton, making it
38 unversally accessible. This provides the ability to register additional
39 autoloaders from anywhere in your code as necessary.
40 </para>
42 <sect2 id="zend.loader.autoloader.usage">
43 <title>Using the Autoloader</title>
45 <para>
46 The first time an instance of the autoloader is retrieved, it
47 registers itself with <code>spl_autoload</code>. You retrieve an
48 instance using the <methodname>getInstance()</methodname> method:
49 </para>
51 <programlisting language="php"><![CDATA[
52 $autoloader = Zend_Loader_Autoloader::getInstance();
53 ]]></programlisting>
55 <para>
56 By default, the autoloader is configured to match the "Zend_" and
57 "ZendX_" namespaces. If you have your own library code that uses
58 your own namespace, you may register it with the autoloader using
59 the <methodname>registerNamespace()</methodname> method. For instance, if your
60 library code is prefixed with "My_", you could do so as follows:
61 </para>
63 <programlisting language="php"><![CDATA[
64 $autoloader->registerNamespace('My_');
65 ]]></programlisting>
67 <note>
68 <title>Namespace Prefixes</title>
70 <para>
71 You'll note that the previous example uses "My_" and not "My".
72 This is because <classname>Zend_Loader_Autoloader</classname> is intended
73 as a general purpose autoloader, and does not make the
74 assumption that a given class prefix namespace includes an
75 underscore. If your class namespace <emphasis>does</emphasis>
76 include one, you should include it when registering your
77 namespace.
78 </para>
79 </note>
81 <para>
82 You can also register arbitrary autoloader callbacks, optionally
83 with a specific namespace (or group of namespaces).
84 <classname>Zend_Loader_Autoloader</classname> will attempt to match these
85 first before using its internal autoloading mechanism.
86 </para>
88 <para>
89 As an example, you may want to utilize one or more eZcomponents
90 components with your Zend Framework application. To use its
91 autoloading capabilities, push it onto the autoloader stack using
92 <methodname>pushAutoloader()</methodname>:
93 </para>
95 <programlisting language="php"><![CDATA[
96 $autoloader->pushAutoloader(array('ezcBase', 'autoload'), 'ezc');
97 ]]></programlisting>
99 <para>
100 This tells the autoloader to use the eZcomponents autoloader for
101 classes beginning with "ezc".
102 </para>
104 <para>
105 You can use the <methodname>unshiftAutoloader()</methodname> method to add the
106 autoloader to the beginning of the autoloader chain.
107 </para>
109 <para>
110 By default, <classname>Zend_Loader_Autoloader</classname> does no error
111 suppression when using its internal autoloader, which utilizes
112 <methodname>Zend_Loader::loadClass()</methodname>. Most of the time, this is
113 exactly what you want. However, there may be cases where you want to
114 suppress them. You can do this using
115 <methodname>suppressNotFoundWarnings()</methodname>:
116 </para>
118 <programlisting language="php"><![CDATA[
119 $autoloader->suppressNotFoundWarnings(true);
120 ]]></programlisting>
122 <para>
123 Finally, there may be times when you want the autoloader to load any
124 namespace. For instance, PEAR libraries do not share a common
125 namespace, making specifying individual namespaces difficult when
126 many PEAR components are in use. You can use the
127 <methodname>setFallbackAutoloader()</methodname> method to have the autoloader
128 act as a catch-all:
129 </para>
131 <programlisting language="php"><![CDATA[
132 $autoloader->setFallbackAutoloader(true);
133 ]]></programlisting>
135 <note>
136 <title>Loading Classes from PHP Namespaces</title>
138 <para>
139 Starting in version 1.10.0, Zend Framework now allows loading classes from
140 <acronym>PHP</acronym> namespaces. This support follows the same guidelines and
141 implementation as that found in the <ulink
142 url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
143 Framework Interop Group PSR-0</ulink> reference implementation.
144 </para>
146 <para>
147 Under this guideline, the following rules apply:
148 </para>
150 <itemizedlist>
151 <listitem>
152 <para>
153 Each namespace separator is converted to a
154 <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
155 </para>
156 </listitem>
158 <listitem>
159 <para>
160 Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
161 <constant>DIRECTORY_SEPARATOR</constant>. The "_" character has no special
162 meaning in the namespace.
163 </para>
164 </listitem>
166 <listitem>
167 <para>
168 The fully-qualified namespace and class is suffixed with ".php" when loading
169 from the file system.
170 </para>
171 </listitem>
172 </itemizedlist>
174 <para>
175 As examples:
176 </para>
178 <itemizedlist>
179 <listitem>
180 <para>
181 <classname>\Doctrine\Common\IsolatedClassLoader</classname> =>
182 <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
183 </para>
184 </listitem>
186 <listitem>
187 <para>
188 <classname>\namespace\package\Class_Name</classname> =>
189 <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
190 </para>
191 </listitem>
193 <listitem>
194 <para>
195 <classname>\namespace\package_name\Class_Name</classname> =>
196 <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
197 </para>
198 </listitem>
199 </itemizedlist>
200 </note>
201 </sect2>
203 <sect2 id="zend.loader.autoloader.zf-version">
204 <title>Selecting a Zend Framework version</title>
206 <para>
207 Typically, you will use the version of Zend Framework that the autoloader you
208 instantiate came with. However, when developing a project, it's often useful to track
209 specific versions, major or minor branches, or just the latest version.
210 <classname>Zend_Loader_Autoloader</classname>, as of version 1.10, offers some features
211 to help manage this task.
212 </para>
214 <para>
215 Imagine the following scenario:
216 </para>
218 <itemizedlist>
219 <listitem>
220 <para>
221 During <emphasis>development</emphasis>, you want to track the latest version of
222 Zend Framework you have installed, so that you can ensure the application works
223 when you upgrade between versions.
224 </para>
226 <para>
227 When pushing to <emphasis>Quality Assurance</emphasis>, however, you need to
228 have slightly more stability, so you want to use the latest installed revision
229 of a specific minor version.
230 </para>
232 <para>
233 Finally, when you push to <emphasis>production</emphasis>, you want to pin to a
234 specific installed version, to ensure no breakage occurs if or when you add new
235 versions of Zend Framework to you server.
236 </para>
237 </listitem>
238 </itemizedlist>
240 <para>
241 The autoloader allows you to do this with the method
242 <methodname>setZfPath()</methodname>. This method takes two arguments, a
243 <emphasis>path</emphasis> to a set of Zend Framework installations, and a
244 <emphasis>version</emphasis> to use. Once invoked, it prepends a path to the
245 <constant>include_path</constant> pointing to the appropriate Zend Framework
246 installation library.
247 </para>
249 <para>
250 The directory you specify as your <emphasis>path</emphasis> should have a tree such as
251 the following:
252 </para>
254 <programlisting language="text"><![CDATA[
255 ZendFramework/
256 |-- 1.9.2/
257 | |-- library/
258 |-- ZendFramework-1.9.1-minimal/
259 | |-- library/
260 |-- 1.8.4PL1/
261 | |-- library/
262 |-- 1.8.4/
263 | |-- library/
264 |-- ZendFramework-1.8.3/
265 | |-- library/
266 |-- 1.7.8/
267 | |-- library/
268 |-- 1.7.7/
269 | |-- library/
270 |-- 1.7.6/
271 | |-- library/
272 ]]></programlisting>
274 <para>
275 (where <emphasis>path</emphasis> points to the directory "ZendFramework" in the above
276 example)
277 </para>
279 <para>
280 Note that each subdirectory should contain the directory <filename>library</filename>,
281 which contains the actual Zend Framework library code. The individual subdirectory names
282 may be version numbers, or simply be the untarred contents of a standard Zend Framework
283 distribution tarball/zipfile.
284 </para>
286 <para>
287 Now, let's address the use cases. In the first use case, in
288 <emphasis>development</emphasis>, we want to track the latest source install. We can do
289 that by passing "latest" as the version:
290 </para>
292 <programlisting language="php"><![CDATA[
293 $autoloader->setZfPath($path, 'latest');
294 ]]></programlisting>
296 <para>
297 In the example from above, this will map to the directory
298 <filename>ZendFramework/1.9.2/library/</filename>; you can verify this by checking the
299 return value of <methodname>getZfPath()</methodname>.
300 </para>
302 <para>
303 In the second situation, for <emphasis>quality assurance</emphasis>, let's say we want
304 to pin to the 1.8 minor release, using the latest install you have for that release. You
305 can do so as follows:
306 </para>
308 <programlisting language="php"><![CDATA[
309 $autoloader->setZfPath($path, '1.8');
310 ]]></programlisting>
312 <para>
313 In this case, it will find the directory
314 <filename>ZendFramework/1.8.4PL1/library/</filename>.
315 </para>
317 <para>
318 In the final case, for <emphasis>production</emphasis>, we'll pin to a specific version
319 -- 1.7.7, since that was what was available when Quality Assurance tested prior to our
320 release.
321 </para>
323 <programlisting language="php"><![CDATA[
324 $autoloader->setZfPath($path, '1.7.7');
325 ]]></programlisting>
327 <para>
328 Predictably, it finds the directory <filename>ZendFramework/1.7.7/library/</filename>.
329 </para>
331 <para>
332 You can also specify these values in the configuration file you use with
333 <filename>Zend_Application</filename>. To do so, you'd specify the following
334 information:
335 </para>
337 <programlisting language="ini"><![CDATA[
338 [production]
339 autoloaderZfPath = "path/to/ZendFramework"
340 autoloaderZfVersion = "1.7.7"
342 [qa]
343 autoloaderZfVersion = "1.8"
345 [development]
346 autoloaderZfVersion = "latest"
347 ]]></programlisting>
349 <para>
350 Note the different environment sections, and the different version specified in each
351 environment; these factors will allow <classname>Zend_Application</classname> to
352 configure the autoloader appropriately.
353 </para>
355 <warning>
356 <title>Performance implications</title>
358 <para>
359 For best performance, either do not use this feature, or specify a specific Zend
360 Framework version (i.e., not "latest", a major revision such as "1", or a minor
361 revision such as "1.8"). Otherwise, the autoloader will need to scan the provided
362 path for directories matching the criteria -- a somewhat expensive operation to
363 perform on each request.
364 </para>
365 </warning>
366 </sect2>
368 <sect2 id="zend.loader.autoloader.interface">
369 <title>The Autoloader Interface</title>
371 <para>
372 Besides being able to specify arbitrary callbacks as autoloaders,
373 Zend Framework also defines an interface autoloading classes may
374 imlement, <classname>Zend_Loader_Autoloader_Interface</classname>:
375 </para>
377 <programlisting language="php"><![CDATA[
378 interface Zend_Loader_Autoloader_Interface
379 {
380 public function autoload($class);
381 }
382 ]]></programlisting>
384 <para>
385 When using this interface, you can simply pass a class instance to
386 <classname>Zend_Loader_Autoloader</classname>'s
387 <methodname>pushAutoloader()</methodname>
388 and <methodname>unshiftAutoloader()</methodname> methods:
389 </para>
391 <programlisting language="php"><![CDATA[
392 // Assume Foo_Autoloader implements Zend_Loader_Autoloader_Interface:
393 $foo = new Foo_Autoloader();
395 $autoloader->pushAutoloader($foo, 'Foo_');
396 ]]></programlisting>
397 </sect2>
399 <sect2 id="zend.loader.autoloader.reference">
400 <title>Autoloader Reference</title>
402 <para>
403 Below, please find a guide to the methods available in
404 <classname>Zend_Loader_Autoloader</classname>.
405 </para>
407 <table id="zend.loader.autoloader.reference.api">
408 <title>Zend_Loader_Autoloader Methods</title>
410 <tgroup cols="4">
411 <thead>
412 <row>
413 <entry>Method</entry>
414 <entry>Return Value</entry>
415 <entry>Parameters</entry>
416 <entry>Description</entry>
417 </row>
418 </thead>
420 <tbody>
421 <row>
422 <entry><methodname>getInstance()</methodname></entry>
423 <entry><classname>Zend_Loader_Autoloader</classname></entry>
424 <entry>N/A</entry>
426 <entry>
427 <para>
428 Retrieve the <classname>Zend_Loader_Autoloader</classname>
429 singleton instance. On first retrieval, it registers
430 itself with <code>spl_autoload</code>. This method is static.
431 </para>
432 </entry>
433 </row>
435 <row>
436 <entry><methodname>resetInstance()</methodname></entry>
437 <entry><code>void</code></entry>
438 <entry>N/A</entry>
440 <entry>
441 <para>
442 Resets the state of the
443 <classname>Zend_Loader_Autoloader</classname> singleton instance to
444 it's original state, unregistering all autoloader callbacks and all
445 registered namespaces.
446 </para>
447 </entry>
448 </row>
450 <row>
451 <entry><methodname>autoload($class)</methodname></entry>
452 <entry><code>string|<constant>FALSE</constant></code></entry>
454 <entry>
455 <itemizedlist>
456 <listitem>
457 <para>
458 <varname>$class</varname>, <emphasis>required</emphasis>.
459 A string class name to load.
460 </para>
461 </listitem>
462 </itemizedlist>
463 </entry>
465 <entry>
466 <para>Attempt to resolve a class name to a file and load it.</para>
467 </entry>
468 </row>
470 <row>
471 <entry><methodname>setDefaultAutoloader($callback)</methodname></entry>
472 <entry><classname>Zend_Loader_Autoloader</classname></entry>
474 <entry>
475 <itemizedlist>
476 <listitem>
477 <para>
478 <varname>$callback</varname>, <emphasis>required</emphasis>.
479 </para>
480 </listitem>
481 </itemizedlist>
482 </entry>
484 <entry>
485 <para>
486 Specify an alternate <acronym>PHP</acronym> callback to use for the
487 default autoloader implementation.
488 </para>
489 </entry>
490 </row>
492 <row>
493 <entry><methodname>getDefaultAutoloader()</methodname></entry>
494 <entry><code>callback</code></entry>
495 <entry>N/A</entry>
497 <entry>
498 <para>
499 Retrieve the default autoloader implementation; by default, this is
500 <methodname>Zend_Loader::loadClass()</methodname>.
501 </para>
502 </entry>
503 </row>
505 <row>
506 <entry><methodname>setAutoloaders(array $autoloaders)</methodname></entry>
507 <entry><classname>Zend_Loader_Autoloader</classname></entry>
509 <entry>
510 <itemizedlist>
511 <listitem>
512 <para>
513 <varname>$autoloaders</varname>,
514 <emphasis>required</emphasis>.
515 </para>
516 </listitem>
517 </itemizedlist>
518 </entry>
520 <entry>
521 <para>
522 Set a list of concrete autoloaders to use in the
523 autoloader stack. Each item in the autoloaders array
524 must be a <acronym>PHP</acronym> callback.
525 </para>
526 </entry>
527 </row>
529 <row>
530 <entry><methodname>getAutoloaders()</methodname></entry>
531 <entry><type>Array</type></entry>
532 <entry>N/A</entry>
533 <entry><para>Retrieve the internal autoloader stack.</para></entry>
534 </row>
536 <row>
537 <entry><methodname>getNamespaceAutoloaders($namespace)</methodname></entry>
538 <entry><type>Array</type></entry>
540 <entry>
541 <itemizedlist>
542 <listitem>
543 <para>
544 <varname>$namespace</varname>, <emphasis>required</emphasis>
545 </para>
546 </listitem>
547 </itemizedlist>
548 </entry>
550 <entry>
551 <para>
552 Fetch all autoloaders that have registered to load a
553 specific namespace.
554 </para>
555 </entry>
556 </row>
558 <row>
559 <entry><methodname>registerNamespace($namespace)</methodname></entry>
560 <entry><classname>Zend_Loader_Autoloader</classname></entry>
562 <entry>
563 <itemizedlist>
564 <listitem>
565 <para>
566 <varname>$namespace</varname>,
567 <emphasis>required</emphasis>.
568 </para>
569 </listitem>
570 </itemizedlist>
571 </entry>
573 <entry>
574 <para>
575 Register one or more namespaces with the default
576 autoloader. If <varname>$namespace</varname> is a string,
577 it registers that namespace; if it's an array of
578 strings, registers each as a namespace.
579 </para>
580 </entry>
581 </row>
583 <row>
584 <entry><methodname>unregisterNamespace($namespace)</methodname></entry>
585 <entry><classname>Zend_Loader_Autoloader</classname></entry>
587 <entry>
588 <itemizedlist>
589 <listitem>
590 <para>
591 <varname>$namespace</varname>,
592 <emphasis>required</emphasis>.
593 </para>
594 </listitem>
595 </itemizedlist>
596 </entry>
598 <entry>
599 <para>
600 Unregister one or more namespaces from the default
601 autoloader. If <varname>$namespace</varname> is a string,
602 it unregisters that namespace; if it's an array of
603 strings, unregisters each as a namespace.
604 </para>
605 </entry>
606 </row>
608 <row>
609 <entry><methodname>getRegisteredNamespaces()</methodname></entry>
610 <entry><type>Array</type></entry>
611 <entry>N/A</entry>
613 <entry>
614 <para>
615 Returns an array of all namespaces registered with the default
616 autoloader.
617 </para>
618 </entry>
619 </row>
621 <row>
622 <entry>
623 <methodname>suppressNotFoundWarnings($flag = null)</methodname>
624 </entry>
626 <entry><code>boolean|Zend_Loader_Autoloader</code></entry>
628 <entry>
629 <itemizedlist>
630 <listitem>
631 <para>
632 <varname>$flag</varname>, <emphasis>optional</emphasis>.
633 </para>
634 </listitem>
635 </itemizedlist>
636 </entry>
638 <entry>
639 <para>
640 Set or retrieve the value of the flag used to
641 indicate whether the default autoloader
642 implementation should suppress "file not found"
643 warnings. If no arguments or a <constant>NULL</constant> value is
644 passed, returns a boolean indicating the status of the flag;
645 if a boolean is passed, the flag is set to that
646 value and the autoloader instance is returned (to
647 allow method chaining).
648 </para>
649 </entry>
650 </row>
652 <row>
653 <entry><methodname>setFallbackAutoloader($flag)</methodname></entry>
654 <entry><classname>Zend_Loader_Autoloader</classname></entry>
656 <entry>
657 <itemizedlist>
658 <listitem>
659 <para>
660 <varname>$flag</varname>, <emphasis>required</emphasis>.
661 </para>
662 </listitem>
663 </itemizedlist>
664 </entry>
666 <entry>
667 <para>
668 Set the value of the flag used to indicate whether
669 or not the default autoloader should be used as a
670 fallback or catch-all autoloader for all namespaces.
671 </para>
672 </entry>
673 </row>
675 <row>
676 <entry><methodname>isFallbackAutoloader()</methodname></entry>
677 <entry><type>Boolean</type></entry>
678 <entry>N/A</entry>
679 <entry>
680 <para>
681 Retrieve the value of the flag used to indicate whether
682 or not the default autoloader should be used as a
683 fallback or catch-all autoloader for all namespaces.
684 By default, this is <constant>FALSE</constant>.
685 </para>
686 </entry>
687 </row>
689 <row>
690 <entry><methodname>getClassAutoloaders($class)</methodname></entry>
691 <entry><type>Array</type></entry>
693 <entry>
694 <itemizedlist>
695 <listitem>
696 <para>
697 <varname>$class</varname>, <emphasis>required</emphasis>.
698 </para>
699 </listitem>
700 </itemizedlist>
701 </entry>
703 <entry>
704 <para>
705 Get the list of namespaced autoloaders that could
706 potentially match the provided class. If none match,
707 all global (non-namespaced) autoloaders are returned.
708 </para>
709 </entry>
710 </row>
712 <row>
713 <entry>
714 <methodname>unshiftAutoloader($callback, $namespace = '')</methodname>
715 </entry>
717 <entry><classname>Zend_Loader_Autoloader</classname></entry>
719 <entry>
720 <itemizedlist>
721 <listitem>
722 <para>
723 <varname>$callback</varname>, <emphasis>required</emphasis>.
724 A valid <acronym>PHP</acronym> callback
725 </para>
726 </listitem>
728 <listitem>
729 <para>
730 <varname>$namespace</varname>,
731 <emphasis>optional</emphasis>. A string representing a class
732 prefix namespace.
733 </para>
734 </listitem>
735 </itemizedlist>
736 </entry>
738 <entry>
739 <para>
740 Add a concrete autoloader implementation to the
741 beginning of the internal autoloader stack. If a
742 namespace is provided, that namespace will be used
743 to match optimistically; otherwise, the autoloader
744 will be considered a global autoloader.
745 </para>
746 </entry>
747 </row>
749 <row>
750 <entry>
751 <methodname>pushAutoloader($callback, $namespace = '')</methodname>
752 </entry>
753 <entry><classname>Zend_Loader_Autoloader</classname></entry>
755 <entry>
756 <itemizedlist>
757 <listitem>
758 <para>
759 <varname>$callback</varname>, <emphasis>required</emphasis>.
760 A valid <acronym>PHP</acronym> callback
761 </para>
762 </listitem>
764 <listitem>
765 <para>
766 <varname>$namespace</varname>,
767 <emphasis>optional</emphasis>. A string representing a class
768 prefix namespace.
769 </para>
770 </listitem>
771 </itemizedlist>
772 </entry>
774 <entry>
775 <para>
776 Add a concrete autoloader implementation to the
777 end of the internal autoloader stack. If a
778 namespace is provided, that namespace will be used
779 to match optimistically; otherwise, the autoloader
780 will be considered a global autoloader.
781 </para>
782 </entry>
783 </row>
785 <row>
786 <entry>
787 <methodname>removeAutoloader($callback, $namespace = '')</methodname>
788 </entry>
790 <entry><classname>Zend_Loader_Autoloader</classname></entry>
792 <entry>
793 <itemizedlist>
794 <listitem>
795 <para>
796 <varname>$callback</varname>, <emphasis>required</emphasis>.
797 A valid <acronym>PHP</acronym> callback
798 </para>
799 </listitem>
801 <listitem>
802 <para>
803 <varname>$namespace</varname>,
804 <emphasis>optional</emphasis>. A string representing a class
805 prefix namespace, or an array of namespace strings.
806 </para>
807 </listitem>
808 </itemizedlist>
809 </entry>
811 <entry>
812 <para>
813 Remove a concrete autoloader implementation from
814 the internal autoloader stack. If a namespace or
815 namespaces are provided, the callback will be
816 removed from that namespace or namespaces only.
817 </para>
818 </entry>
819 </row>
820 </tbody>
821 </tgroup>
822 </table>
823 </sect2>
824 </sect1>