-
Notifications
You must be signed in to change notification settings - Fork 26
DI ( Dependency Injection: Setter, Constructor, Method), AOP ( Aspect Oriented Programming ), Events support, xml, yaml, and annotations (including some JSR 250 and JSR 330, like @configuration and @bean ala java configuration) , lightweight, simple, and quick MVC ( Model View Controller ), syslog, tcp client and server, with non blocking socket…
License
marcelog/Ding
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
Introduction ============ Please contact me if you have any comments, doubts, or any kind of feedback. Send an email to: marcelog@gmail.com Checkout the api (phpdoc) at: http://marcelog.github.com/Ding/php-doc/html/index.html In the homepage, you can find the user manual: http://marcelog.github.com/Ding Ding is also the winner of the 2011 Binpress programming contest :) See these articles for a complete application example: * http://marcelog.github.com/articles/php_applications_with_doctrine2_orm_and_ding_di_container.html * http://marcelog.github.com/articles/php_asterisk_listener_example_using_pami_and_ding.html * Some more articles can be found here http://marcelog.github.com/articles/articles.html Please see inside docs/examples for code samples. A good place to start are the "basic", "aop", "quickstart", "doctrine", and "mvc" examples. -------------------------------------------------------------------------------- Upgrading note -------------------------------------------------------------------------------- If you are upgrading from <= 1.1 to 1.3, please see README.1.3.x. -------------------------------------------------------------------------------- Supported Dependency Injection annotations: * JSR-250: @PostConstruct, @PreDestroy, @Resouce * JSR-330: @Inject, @Named, @Singleton * Spring specific: @Configuration, @Primary, @Value, @Scope, @Component, @Aspect, @Required, @Bean, @Controller, @RequestMapping * Own specific: @Prototype, @InitMethod, @DestroyMethod, @ListensOn, @MethodInterceptor, @ExceptionInterceptor -------------------------------------------------------------------------------- INSTALLATION ------------ See http://marcelog.github.com/articles/ding_how_to_install_configure_tutorial_introduction.html for an indepth look of how to install. -------------------------------------------------------------------------------- CI Server --------- Take a look at the Jenkins CI Server (http://ci.marcelog.name/) to check out the docs, metrics, and pear and phar packages available. -------------------------------------------------------------------------------- Available via Composer ---------------------- Just add the package "marcelog/ding": { "require": { "marcelog/ding": "dev-master" }, "repositories": [ { "type": "pear", "url": "http://pear.apache.org/log4php/" }] } Packagist URL: http://packagist.org/packages/marcelog/ding ------------------------------------------------------------------------------- Available via PEAR ------------------ You can now easily install Ding by issuing: # pear channel-discover pear.marcelog.name # pear install marcelog/Ding or # pear install marcelog/Ding-1.6.3 just replace 1.6.3 by the release version you'd like to install :) See: http://pear.marcelog.name/ Note: A version 1.2.x was erroneously released because of a misconfiguration of the pear channel. To avoid more confusions about the correct versions, 1.2.x will not have any releases. So versions jump from 1.1.x to 1.3.0. If you happen to have a 1.2.0 version installed, please update the pear channel and download the latest version. -------------------------------------------------------------------------------- PHAR File ========= Just go to the Jenkins server at http://ci.marcelog.name and grab the latest phar distribution from the Ding job. -------------------------------------------------------------------------------- Supported bean definitions providers ==================================== * XML * YAML * Annotations (like JSR 250 and 330) -------------------------------------------------------------------------------- Supported annotations ===================== Remember that using annotations is completely optional. Not using them will benefit performance. Annotations CAN be cached. Use the 'annotations' cache with any of the implementations below ;) See these: http://marcelog.github.com/articles/ding_component_bean_annotations.html http://marcelog.github.com/articles/ding_component_bean_annotations_di_dependency_injection.html * @Configuration and @Bean just like Java Configuration. So you dont even need a beans.xml (@Scope, @InitMethod, @DestroyMethod) for this annotated bean definitions. * @Component (used in classes, supports same annotations as @Bean) * @Required * @Resource * @Named * @Inject * @Singleton * @Prototype * @Scope * @PostConstruct * @PreDestroy * @Value * @Bean * @Primary * @Controller (When using the MVC through http). * @RequestMapping (When using the MVC through http). * @InitMethod(method=xxx) * @DestroyMethod(method=xxx) * @Aspect for classes and @ExceptionInterceptor/@MethodInterceptor for methods. * @ListensOn -------------------------------------------------------------------------------- CACHE ===== Ding supports this cache implementations out of the box. * APC. * File. * Zend Cache. * Memcache through memcached php extension (needs libmemcached). * DUMMY. Each one of the implementations can be used for bean caching, beandefinition caching, or proxy caching. Actually, caching beans is a little trickier in the php world. In the java world, the application server is always "up & running", whilst in php everything is created from scratch for every request. So it may be better to not cache the bean itself, but everything else, like definintions and proxies definitions. -------------------------------------------------------------------------------- DI == * Import other beans.xml files anywhere inside your already existant files. This let you split your beans among several configuration files. * Setter injection (php evaluated code, arrays, values, and/or references to other beans). * Constructor injection (php evaluated code, arrays, values, and/or references to other beans). * Method injection (ala spring lookup-method) allows you to have singletons that can deliver prototypes scoped beans. * A bean can be: singleton or prototype (multiple instances). * Can create beans by specifying a static method of the bean class itself. * Can create beans by specifying another bean (and its method) as a factory. * Properties for your beans.xml, like: ${log.dir}/alog.log. You can also have the container setup any php options by specifying a property with the name "php." (i.e: php.date.timezone). * Optional init-method will be called right after assembling a bean. (Can also be specified via the @InitMethod(method=xxx) annotation). * Optional destroy-method will be called when the container is shutting down. (Can also be specified via the @DestroyMethod(method=xxx) annotation). * Supports bean inheritance, via OOP and via xml and yaml definitions. * Supports bean aliasing, via xml, yaml, and annotations. Aware Interfaces ================ IContainerAware: Whenever ding is going to instantiate a bean whose class implements IContainerAware interface, it will inject the container instace to this bean. IBeanNameAware: Whenever ding is going to instantiate a bean whose class implements IBeanNameAware interface, it will inject the bean name. IAspectManagerAware: Whenever ding is going to instantiate a bean whose class implements IAspectManagerAware interface, it will inject the current instance of the aspect manager (giving the ability to inject pointcuts, aspects, and general aop management). IResourceLoaderAware: Whenever ding is going to instantiate a bean whose class implements IResourceLoaderAware interface, it will inject the instance of the resource loader in use, which is usually the container itself. ILoggerAware: Whenever ding is going to instantiate a bean whose class implements ILoggerAware interface, it will inject the instance of the logger (log4php) in use by the container, so you can log there. The returned logger will be of class __CLASS__ (where \ are replaced with .). IReflectionFactoryAware: Whenever ding is going to instantiate a bean whose class implements IReflectionFactoryAware interface, it will inject the instance of the reflection factory in use. Extension points ================ You can easily hook in the bean lifecycle by just implementing one of: * Ding\Bean\Lifecycle\IAfterDefinition * Ding\Bean\Lifecycle\IBeforeCreate * Ding\Bean\Lifecycle\IAfterCreate * Ding\Bean\Lifecycle\IBeforeAssemble * Ding\Bean\Lifecycle\IAfterAssemble * Ding\Bean\Lifecycle\IAfterConfig This will allow you to extend the container functionality as much as you like :) If you want to provider beans yourself, just have a bean implement the Ding\Bean\IBeanDefinitionProvider interface, it will automatically be registered in the container and will be called whenever a new bean definition is demanded. If you want to provide aspects and pointcuts, just implement one or all of: * Ding\Aspect\IAspectProvider * Ding\Aspect\IPointcutProvider The container will automatically register your bean in the aspect manager and will be called to get any new aspects/pointcuts when needed. -------------------------------------------------------------------------------- Events ====== The container natively supports events. This means that you can register beans (either programatically or via the xml, yaml, or annotations drivers) and then asynchronously trigger (dispatch) these events along some data object. The container will then instantiate the needed beans (the listeners) and notify them. Please see docs/examples/events for an example using xml, yaml, and annotations. You can also see this article about working with events: http://marcelog.github.com/articles/ding_event_listen_dispatch_bean.html -------------------------------------------------------------------------------- AOP === Aspects work via an implementation of the interceptor pattern. There are 2 available interceptors, both of them available in xml, yaml, and annotation drivers. * Method: Use this one to be called before every method execution (use proceed() to continue the chained execution), resuming your own afterwards. * Exception: Use this one to be called when an aspected method throws an exception. * Can apply aspects to parent classes See this article for more information: http://marcelog.github.com/articles/ding_php_aop_aspect_oriented_programming.html -------------------------------------------------------------------------------- MVC === The mvc is work in progress, but you can sneak peek it in docs/examples/mvc. You will need a rewrite rule, like (for lighttpd): url.rewrite-if-not-file = ( ".*\?(.*)$" => "/example.php?$1", "" => "/example.php" ) For Apache: RewriteRule ^(.*)$ /example.php/$1 The example is mapped to /Some/Mapped/Path/MyController/some (hint: try it with ?optional=value). If you press the button, the form will be submitted and handled by another action that will print the same data, but now for the post instead of the initial get. Also, if you want to trigger an exception to see the exception handler in action, point your browser to: /Some/Mapped/Path/MyController/someException To try a redirect (no view render, just headers sent), point your browser to /Some/Mapped/Path/MyController/redirect This uses an http header 302. To try an internal redirect (forward), point your browser to /Some/Mapped/Path/MyController/forward. This will internally forward the request to another controller/action. To try annotated controllers (see below), point your browser to /Some/Mapped/Path/MyAnnotatedController/an. MVC Annotations --------------- You can use @Controller and @RequestMapping in your classes and not declare them in beans.xml file. see docs/examples/mvc/annotatedController You can also use Twig to render the views. see docs/examples/mvc-twig You can also use Smarty to render the views. see docs/examples/mvc-smarty Pre And Post Dispatch Interceptors ---------------------------------- You can hook before dispatching a request to a controller and also after. A dispatcher will chain all preHandle() and postHandle() from all the IHandlerInterceptor you configure. A preHandle() interceptor returning true will continue the chain execution. To stop the chained execution, false can be returned, and also a ModelAndView (thus, triggering redirects, view renders, etc). You can find an example in docs/examples/mvc-interceptors -------------------------------------------------------------------------------- TCPClient ========= You can use the helper TCPClientHelper as just another bean. Via callbacks and combining the helpers for error and signal handling, you can easily create a very complete tcp client, using non blocking sockets. Available callbacks: * Before the connection. * As soon as the connection establishes * If the connection failed because of a timeout. * When data is available to be read. * When the connection is closed by either one of the peers. You can specify the connection timeout, the read timeout (both in milliseconds) and the minimum needed bytes in the socket before considering it as available data to be read. see docs/examples/tcp for an example of use. When using non blocking connects, be aware that php will call your error handler with an "operation in progress" message that is completely normal but it seems there is no way to disable it without interferring with other messages :( -------------------------------------------------------------------------------- TCPServer ========= You can use the helper TCPServerHelper as just another bean. Via callbacks and combining the helpers for error and signal handling, you can easily create a very complete tcp server, using non blocking sockets. Available callbacks: * Before opening the socket. * Before binding and listening the socket. * As soon as a connection establishes or closes. * When data is available to be read. * When the connection is closed by either one of the peers. * When there is a read timeout on any of the clients. You can specify the connection timeout, the read timeout (both in milliseconds) and the minimum needed bytes in the socket before considering it as available data to be read. see docs/examples/tcp for an example of use. -------------------------------------------------------------------------------- Error Handling ============== If you declare a bean to listen for event "dingError", it will be called when the container receives an error (same effect as using set_error_handler() by yourself, only much easier!) -------------------------------------------------------------------------------- Signal Handling =============== If you declare a bean to listen for event "dingSignal", it will be called when the container receives a signal, the signal number will be passed as the argument. Only available for SAPI's cli and cgi. Requires the pcntl extension. -------------------------------------------------------------------------------- Shutdown Handling ================= If you declare a bean to listen for event "dingShutdown", it will be called when the container shutdowns (same effect as using register_shutdown_function()). -------------------------------------------------------------------------------- HttpSession =========== A helper so you can access the session from the mvc. You can setAttribute()'s and getAttribute()'s, destroy() it, etc. See the mvc example. -------------------------------------------------------------------------------- PAMIHelper ========== This helper integrates PAMI (https://github.com/marcelog/PAMI) with Ding, offering a quick, easy, and effective way to access and manager asterisk installations via the asterisk manager interface (ami). See: docs/examples/pami -------------------------------------------------------------------------------- PAGIHelper ========== This helper integrates PAGI (https://github.com/marcelog/PAGI) with Ding, offering a quick, easy, and effective way to make agi (Asterisk Gateway Interface) applications (PrePaid systems, voicemail's, etc). See: docs/examples/pagi In order to run the example, you need something like this in your dialplan: [default] exten => _X,1,AGI(/tmp/Ding/docs/examples/pagi/run.sh,a,b,c,d) exten => _X,n,Hangup Call to extension 1 and extension 2 (modify the example if you want another extensions). Use other digit to invoke the default extension. -------------------------------------------------------------------------------- Syslog ====== Try the SyslogHelper to easily add syslogging to your own application. See docs/examples/syslog. -------------------------------------------------------------------------------- Integration with other frameworks ================================= See our doctrine2 integration: https://github.com/marcelog/Ding/tree/master/docs/examples/doctrine -------------------------------------------------------------------------------- Developers ========== * build.xml is a phing build file, not ant. * It's very possible that you may need to edit build.properties. * Available main targets: all, build, test, report. * Tools run: phpdoc, phploc, phpcs, phpmd, phpcpd, phpdepend, phpunit. * Setup your installation by editing pear and php paths in build.properties * Run phing install-dependencies this will install pear and everything needed to run ding tests and metrics. * Run phing all -------------------------------------------------------------------------------- Debugging, logging ================== You need log4php (http://logging.apache.org/log4php/). Just make sure you copy it to the include_path and Ding will pick it up from there. Of course it is recommended that you do not set DEBUG output in your log4php configuration (or remove it from the include path so Ding will notice and not use it). This *will* create a difference in performance. -------------------------------------------------------------------------------- Performance tips ================ * Try to have small include paths. Ding will use the include path for finding resources and autoload your own classes. * Configure the rootLogger and ding logger in ERROR level. * If your code is running on the php module for apache or iis, use apc for all the cache subsytems. Otherwise, use memcached or file. * Do not use annotations at all. Only use the XML or even better, YAML. * If you are using annotations (good for you! just dont abuse ;)) use the annotations cache with apc or memcached or file (in that order). * Do not abuse the aop feature. -------------------------------------------------------------------------------- Collaborators: ============ agvstin | agu.gutierrez@gmail.com -------------------------------------------------------------------------------- ThanksTo -------- jonathaningram for his issue reports. BinPress and all the people involved in the 2011 BinPress Programming Contest. Valery Dubrava for his thoughts, contributions and useful ideas. Alberto Sanchez (jaehoo) --------------------------------------------------------------------------------
About
DI ( Dependency Injection: Setter, Constructor, Method), AOP ( Aspect Oriented Programming ), Events support, xml, yaml, and annotations (including some JSR 250 and JSR 330, like @configuration and @bean ala java configuration) , lightweight, simple, and quick MVC ( Model View Controller ), syslog, tcp client and server, with non blocking socket…
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published