= Configure the parser
:description: How to configure the parser to match your needs
include::revision.txt[]
include::attributes.txt[]


[role="lead"]
You may configure the parser in two ways: _containers_ and _properties_.


== Containers

You can change default containers ('namespaces', 'traits', 'interfaces', 'classes', 'functions', 'includes', 'globals', 'constants'),
and then have different getting methods (rather than standard 'getInterfaces', ... ).


.Containers options
[grid="rows",format="csv"]
[options="header",cols="5,10",role="table table-bordered table-striped"]
|===========================
key code, container default name
use, namespaces
namespace, namespaces
trait, traits
interface, interfaces
class,     classes
function,  functions
require_once, includes
require,      includes
include_once, includes
include,      includes
variable,  globals
constant, constants
|===========================

.Configure the function container
[source,php]
----
<?php
require_once 'Bartlett/PHP/Reflect/Autoload.php';

$source = '/path/to/source_file.php';

try {
    $options = array('containers' => array('function' => 'userFunctions');

    $reflect = new PHP_Reflect($options);
    $reflect->scan($source);

    $functions = $reflect->getUserFunctions();
    // OR
    $functions = $reflect['userFunctions'];

} catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage() . PHP_EOL;
?>
----

== Properties

You can choose what information to retrieve depending of element (key code).

.Properties options
[grid="rows",format="csv"]
[options="header",cols="5,10",role="table table-bordered table-striped"]
|===========================
key code,default property
use,       "file, startEndLines, docblock, alias"
namespace, "file, startEndLines, docblock, alias"
trait,     "file, startEndLines, docblock, namespace, parent, methods"
interface, "file, startEndLines, docblock, namespace, keywords, parent, methods"
class,     "file, startEndLines, docblock, namespace, keywords, parent, methods, interfaces, package"
function,  "file, startEndLines, docblock, namespace, keywords, signature, arguments, ccn, visibility"
require_once, "file, startEndLines, docblock, namespace"
require,      "file, startEndLines, docblock, namespace"
include_once, "file, startEndLines, docblock, namespace"
include,      "file, startEndLines, docblock, namespace"
variable,     "file, startEndLines, docblock, namespace"
constant,  "file, line, docblock, namespace, value"
|===========================

.Configure interface, class and function properties
[source,php]
----
<?php
require_once 'Bartlett/PHP/Reflect/Autoload.php';

$source = '/path/to/PEAR-1.9.2/PEAR.php';

try {
    $options = array(
        'properties' => array(
            'interface' => array(
                'keywords', 'parent', 'methods'
            ),
            'class' => array(
                'keywords', 'parent', 'methods', 'interfaces', 'package'
            ),
            'function' => array(
                'keywords', 'signature'
            ),
        )
    );
    $reflect = new PHP_Reflect($options);
    $reflect->scan($source);

    $classes = $reflect->getClasses();

    print_r($classes['\\']['PEAR_Error']['docblock']);
    print_r($classes['\\']['PEAR_Error']['methods']);

} catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage() . PHP_EOL;
}
?>
----

Here we got only keywords and signature of each class methods.
Class docblock is NULL (first print_r result)
because we have decided NOT to get this property as file, startLine + endLine (startEndLines).

[source,php]
----
<?php

Array
(
    [PEAR_Error] => Array
        (
            [keywords] =>
            [signature] => PEAR_Error($message = 'unknown error', $code = null,
                        $mode = null, $options = null, $userinfo = null)
        )

    [getMode] => Array
        (
            [keywords] =>
            [signature] => getMode()
        )

    [getCallback] => Array
        (
            [keywords] =>
            [signature] => getCallback()
        )

    [getMessage] => Array
        (
            [keywords] =>
            [signature] => getMessage()
        )

    [getCode] => Array
        (
            [keywords] =>
            [signature] => getCode()
        )

    [getType] => Array
        (
            [keywords] =>
            [signature] => getType()
        )

    [getUserInfo] => Array
        (
            [keywords] =>
            [signature] => getUserInfo()
        )

    [getDebugInfo] => Array
        (
            [keywords] =>
            [signature] => getDebugInfo()
        )

    [getBacktrace] => Array
        (
            [keywords] =>
            [signature] => getBacktrace($frame = null)
        )

    [addUserInfo] => Array
        (
            [keywords] =>
            [signature] => addUserInfo($info)
        )

    [__toString] => Array
        (
            [keywords] =>
            [signature] => __toString()
        )

    [toString] => Array
        (
            [keywords] =>
            [signature] => toString()
        )
)
----

.Gets functions signature and their arguments
[source,php]
----
<?php
require_once 'Bartlett/PHP/Reflect/Autoload.php';

$source = '/path/to/PHPUnit/Framework/TestCase.php';

try {
    $options = array(
        'properties' => array(
            'function' => array(
                'signature', 'arguments'
            ),
        )
    );
    $reflect = new PHP_Reflect($options);
    $reflect->scan($source);

    $classes = $reflect->getClasses();

    print_r($classes['\\']['PHPUnit_Framework_TestCase']['methods']);

} catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage() . PHP_EOL;
}
?>
----

And here are results we got on STDOUT :
[source,php]
----
<?php

Array
(
    [methods] => Array
        (
            [__construct] => Array
                (
                    [signature] => __construct($name = NULL, array $data = array(), $dataName = '')
                    [arguments] => Array
                        (
                            [0] => Array
                                (
                                    [name] => $name
                                    [defaultValue] => NULL
                                )

                            [1] => Array
                                (
                                    [typeHint] => array
                                    [name] => $data
                                    [defaultValue] => array()
                                )

                            [2] => Array
                                (
                                    [name] => $dataName
                                    [defaultValue] => ''
                                )

                        )

                )


    ( ... more lines again ... )


            [prepareTemplate] => Array
                (
                    [signature] => prepareTemplate(Text_Template $template)
                    [arguments] => Array
                        (
                            [0] => Array
                                (
                                    [typeHint] => Text_Template
                                    [name] => $template
                                )

                        )

                )

        )

)
----


With this code below (filename reference is __/tmp/ns_sample.php__), we want to get namespaces :

* without imports
* only imports
* all at once

[source,php]
----
<?php
namespace Doctrine\Common\Cache;

use \Memcache;
use My\Full\Classname as Another;

class MemcacheCache extends CacheProvider
{
    public function setMemcache(Memcache $memcache)
    {
    }

}
----

.Getting namespaces in different ways
[source,php]
----
<?php
require_once 'Bartlett/PHP/Reflect/Autoload.php';

$source = '/tmp/ns_sample.php';

try {
    $reflect = new PHP_Reflect();
    $reflect->scan($source);

    $namespaces_without_import = $reflect->getNamespaces();
    // OR 
    $namespaces_without_import = $reflect->getNamespaces(PHP_Reflect::NAMESPACES_WITHOUT_IMPORT);

    $namespaces_only_import    = $reflect->getNamespaces(PHP_Reflect::NAMESPACES_ONLY_IMPORT);

    $namespaces_all            = $reflect->getNamespaces(PHP_Reflect::NAMESPACES_ALL);
    
    print_r($namespaces_without_import);
    print_r($namespaces_only_import);
    print_r($namespaces_all);

} catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage() . PHP_EOL;
}
?>
----

And here are results we got on STDOUT :
[source,php]
----
<?php
Array
(
    [Doctrine\Common\Cache] => Array
        (
            [startLine] => 2
            [endLine] => 13
            [file] => /tmp/ns_sample.php
            [docblock] =>
            [alias] => Cache
            [import] =>
        )

)
Array
(
    [\Memcache] => Array
        (
            [startLine] => 4
            [endLine] => 4
            [file] => /tmp/ns_sample.php
            [docblock] =>
            [alias] => Memcache
            [import] => 1
        )

    [My\Full\Classname] => Array
        (
            [startLine] => 5
            [endLine] => 5
            [file] => /tmp/ns_sample.php
            [docblock] =>
            [alias] => Another
            [import] => 1
        )

)
Array
(
    [Doctrine\Common\Cache] => Array
        (
            [startLine] => 2
            [endLine] => 13
            [file] => /tmp/ns_sample.php
            [docblock] =>
            [alias] => Cache
            [import] =>
        )

    [\Memcache] => Array
        (
            [startLine] => 4
            [endLine] => 4
            [file] => /tmp/ns_sample.php
            [docblock] =>
            [alias] => Memcache
            [import] => 1
        )

    [My\Full\Classname] => Array
        (
            [startLine] => 5
            [endLine] => 5
            [file] => /tmp/ns_sample.php
            [docblock] =>
            [alias] => Another
            [import] => 1
        )

)
----
