<?php

/**

* Generate API documentation.

*

* Run in command line with:

* php -f generate-api.docs.php

*

* Copy output into README.md

*/

$loader = require __DIR__ . '/vendor/autoload.php';

$loader->add('Basecamp\\Test\\', __DIR__ . '/tests');

$docs = new Generate_Docs();

$docs->checkSummaries();

$docs->generate();

$docs->save();

class Generate_Docs {

/**

* @link http://guzzle3.readthedocs.org/webservice-client/guzzle-service-descriptions.html#parameter-schema

* @var array Guzzle service description.

*/

protected $service;

/**

* @var string Generated docs Markdown

*/

protected $docs_markdown;

/**

* Readme filename. Converted to full path on __construct()

*

* @var string

*/

protected $readme_file = 'README.md';

/**

* Markers for identifying start and end of API Calls to be replaced in readme file.

*

* @link( http://stackoverflow.com/a/4829998, Triple hyphen for Pandoc compatibility )

*

* @var string

*/

protected $start_marker = '<!--- START API Generate with: php -f `generate-api-docs.php` -->';

protected $end_marker = '<!--- END API -->';

protected $tmpl_heading = "\n### @summary \n\n";

protected $tmpl_heading_tests = "\n### Unit Test Coverage \n\nThe following service operations are not (yet) covered by unit tests:\n\n";

protected $tmpl_code_block_start = "```php \n";

protected $tmpl_code_block_end = "``` \n";

protected $tmpl_method_without_params = "\$response = \$client->@method(); \n";

protected $tmpl_method_with_params_start = "\$response = \$client->@method( array( \n";

protected $tmpl_method_with_params_end = ") ); \n";

protected $tmpl_method_parameter = " '@param' => @example, // @required @description \n";

protected $tmpl_tests_bullet = "* @method \n";

/**

* Parameter code examples in order of priority.

*

* Note the use of single quotes within double quotes

* so that strings will output as valid PHP.

*

* @var array

*/

protected $examples = array(

// Parameter names

'since' => "'2012-03-24T11:00:00-06:00'",

'description' => "'Example description'",

'content' => "'Example content'",

'name' => "'Example name'",

'data' => "file_get_contents( 'image.jpg' )",

'mimeType' => "'image/jpeg'",

'attachments' => "array( array( 'token' => \$upload_token, 'name' => 'file.jpg' ) )",

'assignee' => "array( 'id' => 1234567, 'type' => 'Person' )",

// Parameter types

'string' => "'example'",

'integer' => 1234567,

);

function __construct() {

$this->service = require __DIR__ . '/src/Basecamp/Resources/service.php';

$this->readme_file = __DIR__ . '/' . $this->readme_file;

}

/**

* Verify that all service operations have summaries set before continuing

*/

public function checkSummaries() {

$need_summaries = array();

foreach ( $this->service['operations'] as $method => $info ) {

if ( ! isset( $info['summary'] ) ) {

$need_summaries[] = $method;

}

}

if ( ! empty( $need_summaries ) ) {

echo PHP_EOL;

echo 'Please set summaries for all operations to generate docs.' . PHP_EOL;

echo 'The following operations are missing a \'summary\' value in service.php:' . PHP_EOL;

foreach ( $need_summaries as $method ) {

echo ' ' . $method . PHP_EOL;

}

echo PHP_EOL;

exit;

}

}

/**

* Work out which serice operations still need unit tests written

*/

public function checkTestCoverage() {

$tests_needed = array();

foreach ( $this->service['operations'] as $method => $info ) {

if ( ! method_exists( new Basecamp\Test\BasecampClientTest(), 'test' . ucfirst($method) ) ) {

$tests_needed[] = $method;

}

}

if ( ! empty( $tests_needed ) ) {

// Test Coverage Heading

echo $this->template( $this->tmpl_heading_tests, array() );

foreach ( $tests_needed as $method ) {

// Test Coverage Heading

echo $this->template( $this->tmpl_tests_bullet, array('method' => $method) );

}

}

}

/**

* Output docs for each service operation in Markdown format.

*/

public function generate() {

ob_start();

foreach ( $this->service['operations'] as $method => $info ) {

// Add method to info array for more convenient templates

$info['method'] = $method;

// Heading

echo $this->template( $this->tmpl_heading, $info );

// Code Block start

echo $this->template( $this->tmpl_code_block_start, $info );

if ( isset( $info['parameters'] ) ) {

// Method call (with parameters) start

echo $this->template( $this->tmpl_method_with_params_start, $info );

// Parameters

foreach ( $info['parameters'] as $param => $param_info ) {

$param_info['param'] = $param;

echo $this->template( $this->tmpl_method_parameter, $param_info );

}

// Method call end

echo $this->template( $this->tmpl_method_with_params_end, $info );

}else {

// Method call (no parameters)

echo $this->template( $this->tmpl_method_without_params, $info );

}

// Code Block end

echo $this->template( $this->tmpl_code_block_end, $info );

}

$this->checkTestCoverage();

$this->docs_markdown = ob_get_clean();

return $this->docs_markdown;

}

public function save() {

if ( ! isset( $this->docs_markdown ) ) {

echo "\nPlease run \$this->generate() before \$this->save()";

exit;

}

if ( ! is_readable( $this->readme_file ) || ! is_writable( $this->readme_file ) ) {

echo "\nCould not read or write to readme file. Please check permissions.\n";

echo "Readme path: {$this->readme_file}\n\n";

exit;

}

$readme = file_get_contents( $this->readme_file );

$this->insertWithMarkers( $this->readme_file, $this->docs_markdown );

echo PHP_EOL . basename( $this->readme_file ) . ' updated.' . PHP_EOL . PHP_EOL;

}

/**

* Inserts an array of strings into a file (.htaccess ), placing it between

* BEGIN and END markers. Replaces existing marked info. Retains surrounding

* data. Creates file if none exists.

*

* @author Unknown. Adapted from WordPress core.

*

* @param string $filename

* @param string $marker

* @param string|array $insertion

* @return bool True on write success, false on failure.

*/

function insertWithMarkers( $filename, $insertion ) {

if ( ! is_array( $insertion ) ) {

$insertion = explode( "\n", $insertion );

}

if ( ! file_exists( $filename ) || is_writable( $filename ) ) {

if ( ! file_exists( $filename ) ) {

$markerdata = '';

} else {

$markerdata = explode( "\n", implode( '', file( $filename ) ) );

}

if ( !$f = @fopen( $filename, 'w' ) )

return false;

$foundit = false;

if ( $markerdata ) {

$state = true;

foreach ( $markerdata as $n => $markerline ) {

if (strpos($markerline, $this->start_marker) !== false) {

$state = false;

}

if ( $state ) {

if ( $n + 1 < count( $markerdata ) )

fwrite( $f, "{$markerline}\n" );

else

fwrite( $f, "{$markerline}" );

}

if ( strpos( $markerline, $this->end_marker ) !== false) {

fwrite( $f, $this->start_marker . "\n" );

if ( is_array( $insertion ) ) {

foreach ( $insertion as $insertline ) {

fwrite( $f, "{$insertline}\n" );

}

}

fwrite( $f, $this->end_marker . "\n" );

$state = true;

$foundit = true;

}

}

}

if ( ! $foundit ) {

fwrite( $f, "\n" . $this->start_marker . "\n" );

foreach ( $insertion as $insertline ) {

fwrite( $f, "{$insertline}\n" );

}

fwrite( $f, $this->end_marker . "\n" );

}

fclose( $f );

return true;

}

return false;

}

/**

* Replace @variables with values in template string.

*

* @param string $string Template string. @variable used for variables.

* @param array $args Array with keys as variable name, values as value

* @return string

*/

protected function template( $string, array $args ) {

// Example data formats

$string = str_replace( '@example', $this->getExample( $args ), $string );

// Required or Optional

$string = str_replace( '@required', ( empty( $args['required'] ) ? 'Optional.' : 'Required.' ), $string );

// Vars from passed array

foreach ( $args as $key => $value ) {

if ( is_string( $value ) ) {

$string = str_replace( '@' . $key, $value, $string );

}

}

// Clear remaining variables

$string = preg_replace( '/@[a-zA-Z0-9]+/', '', $string );

return $string;

}

protected function getExample( array $args ) {

if ( ! isset( $args['param'] ) ) {

return false;

}

foreach ( $this->examples as $key => $code ) {

if ( $key == $args['param'] || $key == @ $args['type'] ) {

return $code;

}

}

return "''";

}

}