ZF2: Writing Service Components

ZF2: Writing Service Components Mike Willbanks | Barnes & Noble

Zend Webinar: Thursday, May 2nd 2013

2

Housekeeping…

• Me  Sr. Web Architect Manager at NOOK Developer

 Open Source Contributor

 Where you can find me:

•  Twitter: mwillbanks G+: Mike Willbanks

•  IRC (freenode): mwillbanks Blog: http://blog.digitalstruct.com

•  GitHub: https://github.com/mwillbanks

3

Agenda

• Background

• ZF2 Service Components

• Writing a Service Component

•  Incorporating your Service Component

Background… Why Service Components

5

A Definition

ZF 1 contained Zend_Service_* components

6

Zend_Service_*

Components were included in the core distribution

7

Zend_Service_*

Make it easy for people to have it available…

8

1.11.13 Release

Caused several issues

9

Started Getting Messy…

Service Component Overview Goals, Lifecycle, and more.

11

RFC March 2012 “RFC Service Components”

Removal of ZF2 Zend\Service namespace into a separate namespace (ZendService) and under their own GitHub project.

Goals of ZF2 Service Components

• Ability to version separately from core framework

• Easier to leverage outside of a ZF context

• Encourage service providers to further contribute

Services for Contribution (Official Services)

• Independently versioned

• Dependencies on framework versions (2.*, 2.0.*, 2.0.1)

• Maintain dependencies by specific packages

• Must follow ZF coding standards

• Must be unique

 A service that does the same thing should not already exist!

14

Discuss on Contributor Mailing

List

CR Team Review Fork Repo

Build ComponentIRC Vote(Meeting Agenda)

Publish!

The Service Component Lifecycle

15

Published ZendService Packages

A published package for ZendService components exist on packages.zendframework.com.

Service Component Maintenance

• Must be maintained for the duration of major versions

 Exceptions must be noted in the ChangeLog

 Component should only state dependency on minor versions

• Maintainers must attempt at all times to keep compatibility with the latest version

 If unable to maintain, actively recruit, if still unable ZF or CR team will make a recommendation on the component.

Writing a Service Component

By example of ZendService\Google\Gcm

General Information

• Service Components are really just like framework libraries

 However, the namespace implies 3rd party integrations.

 They are also organized like the framework.

• Service Components should be reusable for other developers

 Write it out based on the API and not just what you need.

• Create reasonable dependencies

 Zend\Http and Zend\Stdlib being most common.

19

Why Not Modules?

Why Not Modules?

• Modules are more specifically for ZF2 Applications

• Service Components are reusable libraries for any code base.

• Base Rule

 If it involves the MVC; it should more than likely be a module.

21

Starting off…

The file structure of a Service Component.

22

ZendService Components License

https://raw.github.com/zendframework/zf2/master/LICENSE.txt

23

Composer Stub

Main information for your specific library.

24

Composer Stub

Ensure you handle dependencies.

Unit Testing

• Quick Start

 Clone an existing Service Component (Currently no skeleton)

 Copy over files from the tests directory: _autoload.php, Bootstrap.php, phpunit.xml.dist, TestConfiguration.php.dist, TestConfiguration.php.travis

• You will need to customize

 phpunit.xml.dist – Change out the unit test name.

 TestConfiguration.php.dist – Configure your constants and configuration.

Unit Testing

• Tests should contain proper name spacing

 ZendServiceTest\Google\Gcm

• Files you need should be located in an _files directory inside the test area of your component

 tests/ZendService/Google/Gcm/_files

• Write unit tests like normal!

Library Code!

• The guts of the library is what most of us are familiar with

• Write your library inside of your compliant directory

 library/ZendService/Google/Gcm

• Ensure proper namespacing

 ZendService\Google\Gcm

• Attempt to follow great naming so that it makes sense!

Coding Standards

• Remember to make use of the coding standards!

 Docblocks

 Import the proper packages from their respective namespaces

 Read the coding standards doc:

• http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards

• Mainly; PSR-0, PSR-1, PSR-2 (there are slight differences)

Best Practices

• Follow conventions

 PSR-0/1/2, file locations, options classes

• Hard dependencies

 Use the constructor!

 Only set dependencies for items you require!

• Write Tests

 Hook into Travis-CI, go for 100% code coverage

• Discoverability

 Put the component on Packagist, submit it for inclusion to ZendService.

Documentation

• The most dreaded part of the job…

• All of the documentation is in the “zf2-documentation” project under the “zendframework” github organization.

 This will likely change for services in the future.

• Fork the project

• Create a feature branch: feature/service-google-gcm

• Write your documentation

• Submit a PR

31

Documentation is built out of reStructuredText

Yes, Docbook has gone away; so fear not!

32

Language Files

Always start with English first aka “en” as it is the default in the event a translation is missing.

33

Modify docs/language/en/index.rst to add in your new service

Having a table of contents is a good thing!

34

Modify docs/language/en/index.rst to add in your new service

Follow the convention!

35

Write Away!

docs/language/en/modules/zendservice.google.gcm.rst or the like

36

Seeing your Documentation

• Install the proper tools

 apt-get install python-setuptools python-pygments

 easy_install -U Sphinx

• Enter the docs/ directory

• Run: make html

37

Your documentation will now be in:

docs/_build/html

Review for errors before sending the PR

Integrating your Service Add the module to the composer configuration

Add in potential configuration

Setup the service manager

Fetch it inside of a controller

39

Add to your composer.json!

Followed by “php composer.phar install”

40

Handling Configuration

Likely in /path/to/zf2app/config/autoload/local.php

41

Service Manager Setup

Creating a simple factory to get a configured Client.

42

Leveraging your Service Factory in a Controller

We can easily fetch it now when we have a ServiceLocator.

Questions? These slides will be posted to SlideShare & SpeakerDeck.

 SpeakerDeck: http://speakerdeck.com/u/mwillbanks

 Slideshare: http://www.slideshare.net/mwillbanks

 Twitter: mwillbanks

 G+: Mike Willbanks

 IRC (freenode): mwillbanks

 Blog: http://blog.digitalstruct.com

 GitHub: https://github.com/mwillbanks