better versioning of generator and APIs

Author: benbalter

config/config.sample.php

@@ -0,0 +1,19 @@
+<?php
+/**
+ * Main config file for digital strategy report generator
+ * Copy this file to config.php and edit as needed for your installation
+ */
+
+//base directory of project, leave at default for parent directory of this file
+define( 'DGS_BASE_DIR', dirname( dirname( __FILE__ ) ) ); 
+
+//directory where reports will reside afer generation, FALSE to delete after sending to user as a zip file
+define( 'DGS_REPORT_DIR', FALSE );
+
+//base url for schema, change to FALSE to use local information only (e.g., to generate agency and items data files)
+define( 'DGS_SCHEMA_BASE', 'https://raw.github.com/GSA/digital-strategy/1/' ); 
+
+//TTL of disk / in-memory cache ( default is 1 hour )
+define( 'DGS_TTL', 3600 ); 
+
+//that's it!

includes/build-agencies.php

@@ -7,8 +7,11 @@
 require_once 'config/agencies.php';
 require_once 'load.php';
 
+//store generator version
+$dgs_agencies = dgs_prepend_generator_version( $dgs_agencies );
+
 //sort agencies by name alpha ascending
-dgs_sort( $dgs_agencies, 'name' );
+dgs_sort( $dgs_agencies->agencies, 'name' );
 
 //output JSON
 file_put_contents( DGS_BASE_DIR . '/data/agencies.json', json_encode( $dgs_agencies ) );

includes/build-items.php

@@ -7,8 +7,11 @@
 require_once 'config/items.php';
 require_once 'load.php';
 
+//store generator version
+$dgs_items = dgs_prepend_generator_version( $dgs_items );
+
 //sort action items by ID ascending
-dgs_sort( $dgs_items );
+dgs_sort( $dgs_items->items );
 
 //JSON encode the action items array into the json file
 file_put_contents( DGS_BASE_DIR .'/data/items.json', json_encode( $dgs_items ) );

includes/footer.php

@@ -4,7 +4,7 @@
  */
  ?>
  	<footer>
- 		Version 1.0
+ 		Generator Version <?php echo DGS_VERSION; ?>
  	</footer>
     </div> <!-- /container -->
 

includes/functions.php

@@ -359,3 +359,9 @@ function dgs_sort( &$items, $field = 'id' , $dir = SORT_ASC ) {
     array_multisort( $order, $dir, $items );
 
 }
+
+function dgs_prepend_generator_version( $array ) {
+
+	return array_merge( array( 'generator_version' => DGS_VERSION ), $array );
+	
+}

load.php

@@ -16,6 +16,9 @@
 //bootrstrap form generator
 require_once DGS_BASE_DIR . '/includes/forms/load.php';
 
+//generator version, bump with each release
+define( 'DGS_VERSION', '1.1' );
+
 //bootstrap DSG Generator Core
 foreach ( array( 'items', 'agencies' ) as $plural ) {
 

readme.md

@@ -16,12 +16,20 @@ Requirements
 ------------
 
 * PHP (e.g., LAMP, XAMPP, MAMP, etc.)
-* The /tmp/ must be writable by PHP (`chmod 0777 /tmp/` works well)
 
-Usage
------
+Usage and installation
+----------------------
 
-Load index.php in your favorite HTML5 web browser
+1. Clone or extract the project into your web server's `htdocs` or `public_html` folder
+2. Copy `config/config.sample.php` to `config/config.php`
+2. Navigate to the project's folder in your favorite HTML5 web browser (e.g., `http://localhost/dgs/`)
+
+Usage as a service
+------------------
+
+1. Complete step 1 above
+2. POST data directly to the `index.php` file using any language or script of your choice
+3. Recieve a zip file containing the generated content
 
 How it Works
 ------------
@@ -37,6 +45,22 @@ Contributing
 
 Federal employees and members of the public are encouraged to contribue to the project by forking and submitting a pull request. All code must be licensed to the public under GPLv2 or later.
 
+Changelog
+---------
+
+### 1.0 ###
+* Initial Release
+
+### 1.1 ###
+* Better PHP 5.4 compatability (removed calltime pass by reference)
+* Added option to write generated file to web server for easier programatic access (props [Bill Severe](https://github.com/bsevere))
+* Uses PHP's default temporary directory, rather than the `tmp/` folder within the project to generate files, simplifying installation and improving portability (props [Bill Severe](https://github.com/bsevere))
+* Moved configuration to separate file to simplifying customization
+* Better sorting of agencies and action items in datafiles and in the generator (props [Bill Severe](https://github.com/bsevere))
+* Abilitity to bypass GitHub service and local cache to force generation of fresh datafiles
+* Clarified requirements, installation instructions, and usage as a service
+* Corrected typos in readme (props [Bill Severe](https://github.com/bsevere))
+
 License
 -------