Add CallbackContainerBuilder, LoggableContainerBuilder

.travis.yml

@@ -8,7 +8,7 @@ matrix:
     - env: TYPE=coverage
       php: 5.6
     - env: TYPE=UNIT;
-      php: 5.3
+      php: 5.5
     - env: TYPE=UNIT;
       php: hhvm
     - env: TYPE=UNIT;

README.md

@@ -8,7 +8,8 @@
 [![Dependency Status](https://www.versioneye.com/php/onoi:callback-container/badge.png)](https://www.versioneye.com/php/onoi:callback-container)
 
 A simple object instantiator to lazy load registered callback handlers. Part of the
-code base has been extracted from [Semantic MediaWiki][smw] and is now being deployed as independent library.
+code base has been extracted from [Semantic MediaWiki][smw] and is now being
+deployed as independent library.
 
 ## Requirements
 
@@ -22,51 +23,119 @@ the dependency to your [composer.json][composer].
 ```json
 {
 	"require": {
-		"onoi/callback-container": "~1.1"
+		"onoi/callback-container": "~2.0"
 	}
 }
 ```
 
 ## Usage
 
+### CallbackContainerBuilder and CallbackContainer
+
 ```php
 class FooCallbackContainer implements CallbackContainer {
 
-	public function register( CallbackInstantiator $callbackInstantiator ) {
-		$this->addCallbackHandlers( $callbackInstantiator);
+	public function register( ContainerBuilder $containerBuilder ) {
+		$this->addCallbackHandlers( $containerBuilder);
 	}
 
-	private function addCallbackHandlers( $callbackInstantiator ) {
+	private function addCallbackHandlers( $containerBuilder ) {
+
+		$containerBuilder->registerCallback( 'Foo', function( ContainerBuilder $containerBuilder, array $input ) {
+			$containerBuilder->registerExpectedReturnType( 'Foo', '\stdClass' );
 
-		$callbackInstantiator->registerCallback( 'Foo', function( array $input ) {
 			$stdClass = new \stdClass;
 			$stdClass->input = $input;
 
 			return $stdClass;
 		} );
-
-		$callbackInstantiator->registerExpectedReturnType( 'Foo', '\stdClass' );
 	}
 }
 ```
 ```php
-$callbackInstantiator = new DeferredCallbackLoader();
+use Onoi\CallbackContainer\CallbackContainerFactory;
+
+$callbackContainerFactory = new CallbackContainerFactory();
+$containerBuilder = $callbackContainerFactory->newCallbackContainerBuilder();
 
-$callbackInstantiator->registerCallbackContainer( new FooCallbackContainer() );
-$instance = $callbackInstantiator->create(
+$containerBuilder->registerCallbackContainer( new FooCallbackContainer() );
+
+$instance = $containerBuilder->create(
 	'Foo',
 	array( 'a', 'b' )
 );
 
-$instance = $callbackInstantiator->singleton(
+$instance = $containerBuilder->singleton(
 	'Foo',
 	array( 'aa', 'bb' )
 );
 ```
+```php
+return array(
+
+	/**
+	 * @return Closure
+	 */
+	'SomeServiceFromFile' => function( $containerBuilder ) {
+		return new \stdClass;
+	},
+
+	/**
+	 * @return Closure
+	 */
+	'AnotherServiceFromFile' => function( $containerBuilder, $argument1, $argument2 ) {
+		$containerBuilder->registerExpectedReturnType( 'AnotherServiceFromFile', '\stdClass' )
+
+		$service = $containerBuilder->create( 'SomeServiceFromFile' );
+		$service->argument1 = $argument1;
+		$service->argument2 = $argument2;
+
+		return $service;
+	}
+);
+```
+```php
+use Onoi\CallbackContainer\CallbackContainerFactory;
+
+$callbackContainerFactory = new CallbackContainerFactory();
+$containerBuilder = $callbackContainerFactory->newCallbackContainerBuilder();
 
+$containerBuilder->registerFromFile( __DIR__ . '/Foo.php' );
+$someServiceFromFile = $containerBuilder->create( 'SomeServiceFromFile' );
+$anotherServiceFromFile = $containerBuilder->create( 'AnotherServiceFromFile', 'Foo', 'Bar' );
+
+```
 If a callback handler is registered with an expected return type then any
 mismatch of a returning instance will throw a `RuntimeException`.
 
+### LoggableContainerBuilder
+
+`LoggableContainerBuilder` is provided as facade to enable logging and sniffing of
+registered callback instances.
+
+```php
+use Onoi\CallbackContainer\CallbackContainerFactory;
+
+$callbackContainerFactory = new CallbackContainerFactory();
+
+$containerBuilder = $callbackContainerFactory->newLoggableContainerBuilder(
+	$callbackContainerFactory->newCallbackContainerBuilder(),
+	$callbackContainerFactory->newBacktraceSniffer( 10 ),
+	$callbackContainerFactory->newCallFuncMemorySniffer()
+);
+
+$containerBuilder->registerCallbackContainer(
+	new FooCallbackContainer()
+);
+
+$containerBuilder->setLogger(
+	$containerBuilder->singleton( 'SomeLogger' )
+);
+
+```
+
+If a `Psr\Log\LoggerInterface` is set then a similar [output](docs/example.loggable.output.md) will be produced.
+
 ## Contribution and support
 
 If you want to contribute work to the project please subscribe to the
@@ -84,6 +153,12 @@ The library provides unit tests that covers the core-functionality normally run
 
 ## Release notes
 
+- 2.0.0 (2016-11-26)
+ - Added `CallbackContainerFactory`
+ - Added `LoggableContainerBuilder`
+ - Added `CallbackContainerBuilder::registerFromFile` to allow loading callback
+   definitions from a file
+
 - 1.1.0 (2016-09-07)
  - Added `ServicesManager` as convenience class to manage on-the-fly services independent of
    an active `DeferredCallbackLoader` instance
@@ -93,7 +168,7 @@ The library provides unit tests that covers the core-functionality normally run
  - Deprecated the `CallbackLoader` interface in favour of the `CallbackInstantiator` interface
  - Deprecated the `NullCallbackLoader` class in favour of the `NullCallbackInstantiator` class
 
-- 1.0.0 Initial release (2015-09-08)
+- 1.0.0 (2015-09-08)
  - Added the `CallbackContainer` and `CallbackLoader` interface
  - Added the `DeferredCallbackLoader` and `NullCallbackLoader` implementation
 

composer.json

@@ -1,9 +1,9 @@
 {
 	"name": "onoi/callback-container",
 	"type": "library",
-	"description": "A simple callback container registry library",
+	"description": "A very simple callback container/builder library",
 	"keywords": [
-		"cache"
+		"container"
 	],
 	"homepage": "https://github.com/onoi/callback-container",
 	"license": "GPL-2.0+",
@@ -14,11 +14,12 @@
 		}
 	],
 	"require": {
-		"php": ">=5.3.2"
+		"php": ">=5.5",
+		"psr/log": "~1.0"
 	},
 	"extra": {
 		"branch-alias": {
-			"dev-master": "1.x-dev"
+			"dev-master": "2.x-dev"
 		}
 	},
 	"autoload": {

docs/example.loggable.output.md

@@ -0,0 +1,49 @@
+An example output produced by the `LoggableContainerBuilder`.
+
+```
+    "NamespaceExaminer": {
+        "prototype": 3,
+        "prototype-backtrace": [
+            [
+                "require",
+                "require_once",
+                "call_user_func",
+                "{closure}",
+                "SemanticCite::onExtensionFunction",
+                "SCI\\HookRegistry::__construct",
+                "SCI\\HookRegistry::addCallbackHandlers",
+                "SMW\\ApplicationFactory::getNamespaceExaminer",
+                "Onoi\\CallbackContainer\\LoggableContainerBuilder::create"
+            ],
+            [
+                "OutputPage::addParserOutput",
+                "OutputPage::addParserOutputMetadata",
+                "Hooks::run",
+                "call_user_func_array",
+                "SMW\\MediaWiki\\Hooks\\HookRegistry::SMW\\MediaWiki\\Hooks\\{closure}",
+                "SMW\\MediaWiki\\Hooks\\OutputPageParserOutput::process",
+                "SMW\\MediaWiki\\Hooks\\OutputPageParserOutput::canPerformUpdate",
+                "SMW\\MediaWiki\\Hooks\\OutputPageParserOutput::isSemanticEnabledNamespace",
+                "SMW\\ApplicationFactory::getNamespaceExaminer",
+                "Onoi\\CallbackContainer\\LoggableContainerBuilder::create"
+            ],
+            [
+                "SkinTemplate::outputPage",
+                "SkinTemplate::prepareQuickTemplate",
+                "Hooks::run",
+                "call_user_func_array",
+                "SBL\\HookRegistry::SBL\\{closure}",
+                "SBL\\SkinTemplateOutputModifier::modifyOutput",
+                "SBL\\SkinTemplateOutputModifier::canModifyOutput",
+                "SBL\\SkinTemplateOutputModifier::isEnabled",
+                "SMW\\ApplicationFactory::getNamespaceExaminer",
+                "Onoi\\CallbackContainer\\LoggableContainerBuilder::create"
+            ]
+        ],
+        "singleton": 0,
+        "singleton-memory": [],
+        "singleton-time": [],
+        "prototype-memory-median": 1432,
+        "prototype-time-median": 0.00018199284871419
+    },
+```

src/BacktraceSniffer.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace Onoi\CallbackContainer;
+
+/**
+ * @license GNU GPL v2+
+ * @since 2.0
+ */
+class BacktraceSniffer {
+
+	/**
+	 * @var integer
+	 */
+	private $depth = 1;
+
+	/**
+	 * @since 2.0
+	 *
+	 * @param integer $depth
+	 */
+	public function __construct( $depth = 1 ) {
+		$this->depth = $depth;
+	}
+
+	/**
+	 * @see MediaWiki::wfGetCaller
+	 * @since 2.0
+	 *
+	 * @return $string
+	 */
+	public function getCaller( $depth = null ) {
+
+		$depth = $depth === null ? $this->depth : $depth;
+		$backtrace = $this->getBackTrace( $depth + 1 );
+
+		if ( isset( $backtrace[$depth] ) ) {
+			return $this->doFormatStackFrame( $backtrace[$depth] );
+		}
+
+		return 'unknown';
+	}
+
+	/**
+	 * @see MediaWiki::wfGetCallers
+	 * @since 2.0
+	 *
+	 * @return array
+	 */
+	public function getCallers( $depth = null ) {
+
+		$depth = $depth === null ? $this->depth : $depth;
+		$backtrace = array_reverse( $this->getBackTrace() );
+
+
+		if ( !$depth || $depth > count( $backtrace ) - 1 ) {
+			$depth = count( $backtrace ) - 1;
+		}
+
+		$backtrace = array_slice( $backtrace, -$depth - 1, $depth );
+
+		return array_map( array( $this, 'doFormatStackFrame' ), $backtrace );
+	}
+
+	private function doFormatStackFrame( $frame ) {
+		return isset( $frame['class'] ) ? $frame['class'] . '::' . $frame['function'] : $frame['function'];
+	}
+
+	private function getBackTrace( $limit = 0 ) {
+		static $disabled = null;
+
+		if ( $disabled || ( $disabled = !function_exists( 'debug_backtrace' ) ) === true ) {
+			return array();
+		}
+
+		if ( $limit && version_compare( PHP_VERSION, '5.4.0', '>=' ) ) {
+			return array_slice( debug_backtrace( DEBUG_BACKTRACE_PROVIDE_OBJECT, $limit + 1 ), 1 );
+		} else {
+			return array_slice( debug_backtrace(), 1 );
+		}
+	}
+
+}