Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

Symfony Blog:
How we Auto-Deploy Documentation Pull Requests with Platform.sh
Sep 10, 2015 @ 12:42:38

On the Symfony blog Ryan Weaver shares a "behind the scenes" look at how the project handles and has automated their documentation generation process with the help of the Platform.sh service.

[Symfony's documentation](https://github.com/symfony/symfony-docs) is an open source project with more than 800 contributors. That’s great! But our goal is to always make it easier to contribute and faster to merge in changes. And today, we’ve started doing something really cool to improve our workflow: integration with [Platform.sh](https://platform.sh).

Platform.sh is a hosting solution that provides out-of-the-box continuous deployment for Symfony, Drupal and any other PHP applications. It extends the concept of a Git branch at the infrastructure level. Basically, this means that it’s easy to deploy every branch and/or Pull Request to its own URL.

He talks about the documentation's format (Sphinx) and how, while it does provide flexibility it also can lead to maintenance issues too. Changes can't be seen immediately and it's difficult to review. Instead they worked up a process where each pull request was automatically deployed to its own unique URL. This reduces both issues they were setting around instant feedback and review problems and provides a better experience for the developer overall.

tagged: integration platformsh documentation request pull symfony continuous deployment

Link: http://symfony.com/blog/how-we-auto-deploy-documentation-pull-requests-with-platform-sh

SitePoint PHP Blog:
Fast Multi-language Docs with SitePoint’s RTDSphinx-PHP
Sep 09, 2015 @ 12:42:50

The SitePoint PHP blog has a tutorial posted showing you how to create multi-language documentation with ReadTheDocs and Sphinx with the help of the RTDSphinx-PHP library.

This post will guide you through getting up and running with RTDSphinx-PHP, a ReadTheDocs-friendly Sphinx based PHP documentation skeleton with sane defaults, pre-installed directives, and modified styles for optimal API and prose documentation rendering in multiple languages. For an unfinished example of the documentation, see here and switch the language in the bottom left flyout panel.

If this sounds familiar, it’s because we already went through a manual setup of a similar skeleton in a previous post, but that one had no localization support, too many steps, and wasn’t as reusable as this newly developed one.

He starts with the "quickstart" instructions to help you get the necessary tools installed to create the documentation. From there he gets into some of the main features the library provides including localization, a few utility scripts and syntax highlighting. Each of these comes with a bit of code/markup showing how to put them to use. The post ends with the instructions you'll need to push the documentation you've created up to ReadTheDocs and what the results should look like.

tagged: documentation multilanguage language readthedocs sphinx library

Link: http://www.sitepoint.com/fast-multi-language-docs-with-sitepoints-rtdsphinx-php/

SitePoint PHP Blog:
Using Sphinx for PHP Project Documentation
Aug 17, 2015 @ 09:19:04

The SitePoint PHP blog has posted a guide to using Sphinx, a documentation generation tool that's used behind the scenes for the ReadTheDocs hosted documentation service.

I recently had the need to write proper prose-like source-code documentation for the Diffbot PHP client. Having looked at several documentation generators, and even having suggested a @prose tag for importing of related MD/reST documents into method and class descriptions, I realized there simply is no perfect solution we can all agree on (yet). So until I extend Sage with a @prose token and reST parsing, I opted for ReadTheDocs and Sphinx.

He starts with a quick "TL;DR" of the necessary commands to get things working quickly but follows it with the full details. He walks you through the installation of Sphinx locally, setting up the folders and adding a custom theme. He show how to create the table of contents, activate the PHP syntax highlighting and how to show/hide the "Edit on GitHub" links. He also includes the steps to convert Markdown documents into the reST format and, finally, adding the project to the ReadTheDocs site and pushing your results.

tagged: sphinx project documentation tutorial readthedocs markdown rest

Link: http://www.sitepoint.com/using-sphinx-for-php-project-documentation/

PHP Roundtable:
026: Documentation & Developer Experience
Aug 05, 2015 @ 08:44:24

The PHP Roundtable podcast, hosted by PHP community member Sammy K Powers, has posted their latest episode - episode #26: Documentation & Developer Experience. Sammy is joined by guests Ryan Weaver, Taylor Otwell and Frank de Jonge.

Documentation can make or break a project but it's often completely overlooked until the very end. And if we don't think about how developers will interact with our project before writing our opening We'll discuss some strategies we can take to improve the overall developer experience with "good" documentation and clean API's

You can catch this latest episode either through the embedded video player on the PHP Roundtable site or directly on YouTube. If you enjoy the episode, be sure to subscribe to their feed and follow them on Twitter for notifications when the live recordings are happening.

tagged: phproundtable podcast video ep26 documentation developer experience

Link: https://www.phproundtable.com/episode/documentation-and-developer-experience

Rob Allen:
First beta of Slim Framework 3
Jul 03, 2015 @ 08:03:18

Rob Allen has a new post about the tagging of the first beta of Slim Framework v3, the popular PHP microframework's latest version. In it he details a few of the major changes and requests help testing.

Last night, I tagged beta 1 of Slim Framework 3! This is a significant upgrade to v2 with a number of changes that you can read on the Slim blog. For me, the two key features that I'm most excited about are: PSR-7 support, [...and a] dependency injection container with container-interop compliance. [...] There's lots of other changes and we believe we have kept to the key tenants of Slim, keeping it focussed as a micro-framework suitable for building any application that you want to build.

He includes everything you'll need to test this newly tagged release with the help of his skeleton application. He also links to the new documentation that's a work in progress to replace the current set of docs. You can find more information on the full list of changes over on the Slim blog.

tagged: slim microframework framework slim3 beta tagged testing documentation

Link: http://akrabat.com/first-beta-of-slim-framework-3/

Sammy Powers:
Contributing to the PHP Manual
Jun 19, 2015 @ 13:23:27

If you've wanted to contribute something back to PHP but aren't familiar with C (or don't feel comfortable enough with it) Sammy Powers offers another solution. In his latest post he shows you how to contribute to the PHP documentation and update the manual for new features, missing information or fixes to current code examples.

If you've been wanting to contribute to PHP internals, starting with the documentation can be a great entry point; especially because it doesn't require dusting off those old C books from college. But knowing where to start can be tricky since information on how to contribute to the docs is scattered across the internet. This article is a step-by-step guide of how to contribute documentation to the PHP manual.

He starts with the "quick and dirty" way of editing the manual through the edit.php.net site, but points out that it's really only useful for smaller changes, not large documentation updates. The rest of the post shows you how to set up the documentation locally and generate the results to validate your changes. He talks some about the DocBook format they're written in, the build process with the PhD (PHP docs generator) and running the php.net test suite against the changes. This ensures that nothing else has broken on the site in the process.

He shows you where to make your changes, how to generate it from either a skeleton or using the docgen script and submitting the changes back to the repository. There's also a few other random changes to make before committing the files back via SVN and pushing them back upstream. He ends the post talking about the GoPHP7-ext project and how to find extensions that are missing documentation or where it's incomplete (easy thanks to an included "check-missing-docs" file included in the repository).

tagged: contribute documentation phpnet manual extension gophp7ext docgen tutorial

Link: https://www.sammyk.me/how-to-contribute-to-php-documentation

Laravel Podcast:
Episode 28: Documentation, JavaScript, & Conspiracy Theories
Jun 01, 2015 @ 10:26:50

The Laravel Podcast, with host Matt Stauffer and guests Taylor Otwell and Jeffrey Way, has posted their latest episode today: Episode 28: Documentation, JavaScript, & Conspiracy Theories.

In this episode, the crew discusses recent improvements to the Laravel documentation, Vue.js, ECMAScript 6, and a few conspiracy theories.

You can listen to this latest episode in a few different ways. You can either use the in-page audio player, download the mp3 or subscribe to their feed and get this and future episodes delivered directly to your reader of choice.

tagged: laravel podcast ep28 documentation javascript conspiracy theory vuejs ecmascript

Link: http://www.laravelpodcast.com/episodes/12660-episode-28-documentation-javascript-conspiracy-theories

SitePoint PHP Blog:
Generating PHP Documentation with Sami
Apr 28, 2015 @ 09:55:31

The SitePoint PHP blog has a new tutorial posted today showing you how to generate API documentation with Sami, a "Friends of PHP" project that's currently used to generate API documentation similar to what the Symfony project provides. In this case "API" refers to your class and method structures, not something like a REST API.

Documenting your methods, classes, and functions is becoming second nature for everyone, so it makes sense to have a way to generate a separate documentation instead of navigating through the source code. In this article, I’m going to introduce you to Sami, the new API documentation generator.

He starts with a brief introduction to the DocBlock commenting methods and why you might want to choose Sami over other document generation tools (like phpDocumentor). He then helps you get Sami installed as a phar archive and how to use it to generate the document output for the Laravel Illuminate package. He includes the code you can use to set up the Sami configuration and an example of the output from the command execution. He then includes a bit about the versioning of the documentation, using themes and customizing the look and feel through custom assets and markup changes.

tagged: sami api documentation generate tutorial symfony introduction

Link: http://www.sitepoint.com/generating-php-documentation-sami/

SitePoint PHP Blog:
Testing APIs with RAML
Feb 24, 2015 @ 10:19:39

The SitePoint PHP blog has a new tutorial posted today showing you how to test your API via RAML, using the structure it defines to verify the requests and responses made to the API. This is the second part of the series and you can find part one (the introduction to RAML) here.

In a recent article I looked at RESTful API Modeling Language (RAML). I provided an overview of what RAML is all about, how to write it and some of its uses. This time, I’m going to look at some of the ways in which you can use RAML for testing. We’ll start by using RAML to validate responses from an API. Then we’ll look at an approach you could take to mock an API server, using a RAML file to create mock HTTP responses.

He starts off by defining a basic RAML document that defines an "Albums" structure with endpoints for "account" and "albums" with various data beneath each one (and created an application that follows it). He then shows how to combine Guzzle, PHPUnit and a RAML parser to grab the API definition and set up a sample test. A simple example test is provided showing you how to check the validity of a response structure. Then he gets into mocking the API using the RAML structure using the FastRoute router. He creates a mock object and a "dispatch" method to handle the request routing based on the contents of the RAML document. He also includes a method to check the parameter values on a request, ensuring they're the correct types.

tagged: tutorial testing unittest phpunit raml api documentation mock fastroute

Link: http://www.sitepoint.com/testing-apis-raml/

SitePoint PHP Blog:
RAML, the RESTful API Modeling Language
Feb 02, 2015 @ 10:52:58

The SitePoint PHP blog has a new post today introducing RAML, a modeling language made specifically for use in APIs to define services available.

n a recent article I introduced Slate, a static site generator specifically designed for writing API documentation. This time around, I’m going to look at something which in many ways is even better. But first, if you’ll indulge me for just a moment, I’d like to begin by quoting myself from that article; "[an] API is only as good as its documentation." I think it’s worth repeating, since it’s all-too-frequently overlooked, and it’s one of the motivations for this short series of articles on some of the tools out there to help you write great documentation.

RAML (RESTful API Modeling Language) provides a structured, unambiguous format for describing a RESTful API. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more.

He starts off with a few things that RAML is particularly good at helping with, including being used to generate other documentation. He then moves into writing up some of the actual RAML documentation, noting that it's a derivative of YAML and is just made from text files. He walks through the creation of a sample RAML document including the overall summary information, describing resources, HTTP methods and response structure. He also includes examples of defining query parameters, request data and any security requirements you might have. Finally, he suggests the raml2html tool if you want to generate some HTML output of your configuration, making it easier for normal humans to read.

tagged: raml api rest modeling language documentation requirements endpoints

Link: http://www.sitepoint.com/raml-restful-api-modeling-language/