ptero 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4da3a464d447bcedad4e6dcbcef6f91c508185fb
+  data.tar.gz: 097dec9857ca53e7383297ccbc291bbcc7933d9c
+SHA512:
+  metadata.gz: 25e1ff3a390dbcb356212a3b520fb7dc676e58c2f669d326a7a77b36c8e54feb1696747164af8c5a1fcad7b0a8ad21e2f2cbc198ac81d18be0253674da7b282c
+  data.tar.gz: 5b3ca3cd4dd4bafae1d3c8d504e996706898af8185d4fe671f8e023f8f9324ccd67b93fa19dfaf052e48c546b6552c36854f1023d3be9e6d6d83a4fefa27c632

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*~

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ptero.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 AndrewTLee
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,350 @@
+### Ptero
+Ptero is a fast and flexible model-view-controller framework for PHP. It allows you to generate models, views, controllers, and routes instantly over the command-line and automatically provides a strong, clean structure for running web apps.
+
+Think wearing a giant robot exo-skeleton with lasers and missile launchers while crushing the puny challenges of archaic PHP in a two-hour-long feature film directed by Michael Bay. It's that good.
+
+
+### It has the good stuff
+Features include:
+  * RESTful routing
+  * Sensible templates: layouts and views separate
+  * RoR-esque code generation
+  * PHP-ActiveRecord for ORM: No SQL needed!
+  * Installs dependencies quickly and easily with Composer
+  * Built in Ruby: Who doesn't love Ruby?
+
+### It takes care of the bad stuff
+Don't worry about:
+  * annoying PHP syntax errors
+  * copy-pasting or otherwise repeating code
+  * SQL, SQL injection, escaping strings, etc
+  * URLs that look ugly
+  * PHP being stupid in general
+
+### How do I do it?
+To start using Ptero, make sure your PHP command-line tool is up-to-date, then run the following:
+```bash
+$ gem install ptero
+```
+
+Now make an application:
+```bash
+$ ptero new Blog
+```
+
+There! Your web application is seeded and ready. Now you can start generating files.
+```bash
+$ cd Blog
+$ ptero generate page hippo
+$ ptero route /hippo Hippo
+```
+Now run an apache server with root directory Blog/www, and navigate to http://localhost/hippo to see a fully-formed page.
+
+(I really should have a built-in server command, but making Ruby run PHP is a mess. If someone wants to write up a cross-platform WEBrick server for PHP, I would be glad to incorporate it)
+
+### Onward!
+Now for the best part. Let's take a look at the generated code.
+
+Here's the default controller, Blog/php/controllers/HippoController.php
+```php
+/*
+ *
+ * HippoController.php
+ * ===================
+ * This controller does ...
+ *
+ */
+ 
+namespace Blog\Controllers;
+
+
+class HippoController extends ApplicationController {
+	
+	// Handle GET requests, use 'public function post()' to handle POST
+	public function get() {
+		// Render template
+		$this->render();
+	}
+	
+}
+```
+
+The controller inherits from ApplicationController, giving it all sorts of useful functionality, most notably the render() method.
+
+Calling $this->render(); with (or without) an array mapping of arguments will automatically render the template of the same name as the controller, in this case Blog/views/hippo.html.twig.
+
+Here it is:
+
+```twig
+{% extends 'application.html.twig' %}
+
+{% block head %}
+	<!-- HTML head code produced by view: hippo -->
+	<script type="text/javascript" src="/assets/js/hippo.js"></script>
+	<link rel="stylesheet" type="text/css" src="/assets/css/hippo.css" />
+{% endblock %}
+
+{% block content %}
+	<!-- HTML content code produced by view: hippo -->
+	<h2>View: Hippo</h2>
+
+{% endblock %}
+
+```
+This template is written in Twig. [Click here](http://twig.sensiolabs.org) to learn the basics of Twig.
+
+
+Notice that the template has only a few lines of code, and that it extends a layout, called application.html.twig. 
+
+In this way, global layout changes can be made to the global application template, and individual changes made to individual pages. 
+
+For example, let's try doing some arbitrary server-side work and sending it to the client:
+```php
+// HippoController.php
+
+class HippoController extends ApplicationController {
+	
+	// Handle GET requests, use 'public function post()' to handle POST
+	public function get() {
+		// sum the numbers 1-10
+		$sum = 0;
+		for($i=1;$i<10;$i++) {
+			$sum += $i;
+		}
+		$this->render(array(
+			'sum' => $sum
+		));
+	}
+	
+}
+```
+the template:
+```twig
+{% extends 'application.html.twig' %}
+
+{% block head %}
+	<!-- HTML head code produced by view: hippo -->
+	<script type="text/javascript" src="/assets/js/hippo.js"></script>
+	<link rel="stylesheet" type="text/css" src="/assets/css/hippo.css" />
+{% endblock %}
+
+{% block content %}
+	<!-- HTML content code produced by view: hippo -->
+	<h2>The sum is: {{sum}}</h2>
+
+{% endblock %}
+
+```
+Now our code will print the $sum variable passed to it by the server.
+
+### Routing
+We already did some routing with the `$ptero route` command, but routes are also stored in a file and editable by hand. Let's open Blog/php/routes.php
+```php
+// Application route maps
+$application->route(array(
+	
+	  '/hippo' => 'Blog\Controllers\HippoController',
+));
+
+```
+Look! The route we made is there! It maps the string '/hippo' to the controller class Blog\Controllers\HippoController.
+
+You can also print all current routes by running
+```bash
+$ ptero routes
+```
+
+We can try using RESTful parameters in our application and passing them to controllers. Try this:
+```bash
+$ ptero generate page rhino
+$ ptero route /rhino/:number Rhino
+```
+Now edit php/controllers/RhinoController.php:
+```php
+namespace Blog\Controllers;
+
+
+class RhinoController extends ApplicationController {
+	
+	// Handle GET requests, use 'public function post()' to handle POST
+	public function get($number) {
+		$number = intval($number);
+		$result = $number * $number;
+		$this->render(array(
+			'result' => $result
+		));
+	}
+	
+}
+```
+and make the template print our result:
+```twig
+{% block content %}
+	<!-- HTML content code produced by view: rhino -->
+	<h2>View: Rhino</h2>
+	<div>
+		Result: {{ result }}
+	</div>
+
+{% endblock %}
+```
+
+Now navigate to http://localhost/rhino/74
+
+Yay! Our application can compute squares!
+
+Routes in the routes.php file support a full range of regular expressions, although stubs such as :number and :alpha can be useful. Learn more at <https://github.com/anandkunal/ToroPHP>
+
+### DATABASES!!!
+
+Ptero wouldn't be complete without Databases, though, (as-of-yet) we have not incorporated the ability to generate them through the command-line tool.
+
+You'll have to bring your own SQL server. Sorry. Try [MAMP](http://www.mamp.info/en/).
+
+Ptero uses PHP-ActiveRecord Databases, which are as easy as pie to use with a few minutes' practice. [Take a look.](http://www.phpactiverecord.org/projects/main/wiki/Quick_Start)
+
+The first step of using Ptero databases is to configure your application. Open config/config.php:
+```php
+<?php
+/*
+ * config.php
+ * return array of configuration values
+ *
+ *
+ *
+ */
+
+
+return array(
+	  'templates_path' => 'views',
+	  
+	  'controllers_path' => 'php/controllers',
+	  
+	  'models_path' => 'php/models',
+	  
+	
+	
+	'database' => array(
+		'name'     => 'database-name',
+		'user'     => 'username',
+		'password' => 'password',
+		'server'   => 'localhost'
+	)
+)
+?>
+```
+Change the values 'database-name', 'username', 'password', and 'server' to the configuration of your database so that PHP-ActiveRecord knows where to look.
+
+Now let's generate another page. We'll assume that we have a table called Elephants in our database that has a primary-key int "id", a string "name", and another int "age."
+```bash
+$ ptero generate page elephant
+$ ptero generate model elephant
+$ ptero route /elephants/:number Elephant
+```
+In php/controllers/ElephantController.php:
+```php
+<?php
+
+/*
+ *
+ * ElephantController.php
+ * ======================
+ * This controller does ...
+ *
+ */
+
+namespace Blog\Controllers;
+use \Blog\Models as DB; // Make sure we can access Models
+
+class ElephantController extends ApplicationController {
+	
+	// Handle GET requests, use 'public function post()' to handle POST
+	public function get($id) {
+		$this->db_connect('development'); // Connect to our database, in the mode specified. 'development' is the default value. 
+		
+		$id = intval($id);
+		$elephant = DB\Elephant::find($id);
+		
+		$name = $elephant->name;
+		$age = $elephant->age;
+		$this->render(array(
+			'name' => $name,
+			'age' => $age
+		));
+	}
+	
+}
+
+
+?>
+```
+In views/elephant.twig:
+```twig
+{% extends 'application.html.twig' %}
+
+{% block head %}
+	<!-- HTML head code produced by view: elephant -->
+	<script type="text/javascript" src="/assets/js/elephant.js"></script>
+	<link rel="stylesheet" type="text/css" src="/assets/css/elephant.css" />
+{% endblock %}
+
+{% block content %}
+	<!-- HTML content code produced by view: elephant -->
+	<h2>View: Elephant</h2>
+	<h2>Name: {{ name }}</h2>
+	<h2>Age: {{ age }}</h2>
+
+{% endblock %}
+```
+With this code in place, a request to http://localhost/elephants/n will output the information of elephant with id=n.
+
+In this same way, you can create new Elephants and save them to the database by running something akin to:
+```php
+  $dumbo = new \Blog\Models\Elephant();
+	$dumbo->name = 'dumbo';
+	$dumbo->age = 25;
+	$dumbo->save();
+```
+In the post() method of a controller.
+
+### Inverse Commands
+Each "create" command has an inverse command to undo it.
+
+This "destroy" command will delete or undo a create operation.
+
+USE WITH CARE ON UNCOMMITTED CHANGES.
+
+Here are some common inverse commands:
+```bash
+$ ptero new Slideshow               # Create the Slideshow application
+$ cd Slideshow
+
+$ ptero generate controller Index
+$ ptero remove controller Index     # remove is the inverse of generate
+
+$ ptero route /asdf/:alpha.jpg Tree
+$ ptero unroute /asdf/:alpha.jpg    # unroute is the inverse of route
+
+
+$ ptero destroy                     # destroy is the inverse of new, it will destroy a named directory or the current one
+```
+
+### Conclusion
+Ptero is still in a phase of development, so please contact @LuminousRubyist, the creator and maintainer of this project, for any questions, comments, complaints, insults, or profound observations about everyday life.
+
+
+### Contributing
+
+1. Fork it ( https://github.com/luminousrubyist/ptero/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+
+### Thank you
+Thank you to all the libraries, and services that make this possible:
+  * [PHP-ActiveRecord](http://www.phpactiverecord.org/)
+  * [Twig](http://twig.sensiolabs.org/)
+  * [ToroPHP](https://github.com/anandkunal/ToroPHP)
+  * [Composer](https://getcomposer.org/)

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/bin/ptero

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'ptero'
+require 'colorize'
+
+begin
+  # Run the Ptero command-line
+  Ptero::CLI::Root.start(ARGV)
+rescue Ptero::Exception => e
+  # Report Ptero::Exception and subclasses to the user
+  puts "#{'Error:'.red} #{e.message}"
+  puts "  Exception type: #{e.class}"
+end

data/lib/ptero.rb

@@ -0,0 +1,14 @@
+require 'ptero/version'
+require 'ptero/exception'
+require 'ptero/generator'
+require 'ptero/cli'
+require 'ptero/application'
+require 'pathname'
+
+# The namespace for all Ptero classes and constants
+module Ptero
+  
+  # The directory location of all Ptero templates for code generation
+  TEMPLATE_PATH = Pathname.new("#{__dir__}/ptero/templates")
+  
+end

data/lib/ptero/application.rb

@@ -0,0 +1,281 @@
+# application.rb
+# ==============
+# This class represents a single application built with ptero.
+# It uses generators to orchestrate the creation of an application, and also oversees composer dependencies and installations
+
+require 'json'
+require 'pathname'
+require 'colorize'
+require 'fileutils'
+require 'open3'
+
+module Ptero
+  # Each instance of this class represents a Ptero application. Within its directory,
+  # this class is used to test the presence of PHP, download the composer.phar file, install composer dependencies, and use Generators to automatically create
+  # new files and components in the application.
+  class Application
+    
+    # Input a directory String or Pathname to make a new Application from that path. (Defaults to Dir.pwd)
+    # @param dir [Pathname,String] the Application directory
+    def initialize(dir=Dir.pwd)
+      @name = dir.to_s.split('/').last.capitalize
+      @dir = Pathname.new(dir)
+      
+      
+    end
+    
+    attr_reader :name,:dir
+    
+    # Find out whether or not the user has the PHP command-line tool installed so that they can use Composer.
+    # @return [Boolean] whether or not the user's PHP command works.
+    def test_php
+      Dir.chdir @dir do
+        `php -r'echo "Success!";'` == 'Success!'
+      end
+    end
+    
+    # Download the composer.phar file into the Application directory using the command
+    # 'curl -sS https://getcomposer.org/installer | php' as prescribed on the Composer website
+    # 
+    # @return [Application,Boolean] self
+    def get_composer
+      raise Ptero::Exception::ApplicationException, "Application #{self} already has composer.phar file" if has_composer?
+      Dir.chdir @dir do
+        # Download code from the composer website
+        # https://getcomposer.org
+        Open3.popen3("php -r \"readfile('https://getcomposer.org/installer');\" | php") do |stdin,stdout,stderr|
+          print 'Downloading composer'
+          stdout.each_line do |line|
+            print '.'
+          end
+          puts
+          puts 'Done!'
+        end
+      end
+      self
+    end
+    
+    # Remove the composer.phar file
+    # @return [Application,Boolean] self if composer was removed, flse if composer is not downloaded
+    def remove_composer
+      raise Ptero::Exception::ApplicationException, "Application #{self} does not have a composer.phar file" unless has_composer?
+      File.unlink(dir.join('composer.phar'))
+      self
+    end
+    
+    # Find out if this Application has the composer.phar file.
+    # @return [Boolean] whether or not composer.phar was found
+    def has_composer?
+      Dir.chdir @dir do
+        File.exist? 'composer.phar'
+      end
+    end
+    
+    # Install all dependencies listed in the composer.json file using Composer
+    # 'php composer.phar install'
+    # @return [Application] self
+    def install_dependencies
+      raise Ptero::Exception::ApplicationException, "Not a dinosaur root: #{Dir.pwd}" unless verify
+      raise Ptero::Exception::ApplicationException, "PHP command-line tool failed, update your version of PHP" unless test_php
+      Dir.chdir @dir do
+        # Install dependencies using Composer
+        # https://getcomposer.org
+        Open3.popen3('php composer.phar install') do |stdin,stdout,stderr|
+          print 'Installing dependencies'
+          stdout.each_line do |line|
+            print '.'
+          end
+          puts
+          puts 'Done!'
+        end
+      end
+      self
+    end
+    
+    # Update all dependencies listed in the composer.json file using Composer
+    # 'php composer.phar update'
+    # @return [Application] self
+    def update_dependencies
+      raise Ptero::Exception::ApplicationException, "Not a dinosaur root: #{Dir.pwd}" unless verify
+      raise Ptero::Exception::ApplicationException, "PHP command-line tool failed, update your version of PHP" unless test_php
+      Dir.chdir @dir do
+        # Update dependencies using Composer
+        # https://getcomposer.org
+        Open3.popen3('php composer.phar update') do |stdin,stdout,stderr|
+          stdout.read
+        end
+      end
+      self
+    end
+    
+    def remove_dependencies
+      FileUtils.rm_r(dir.join('vendor'))
+    end
+    
+    def dependencies_installed?
+      @dir.join('vendor').directory?
+    end
+    
+    # Find out if this folder really contains a Ptero application using metadata in composer.json
+    # @return [Boolean] whether or not this application was verified successfully.
+    def verify
+      composer_path = dir.join('composer.json')
+      return false unless File.exist? composer_path
+      hash = JSON.parse File.read(composer_path)
+      return false unless hash['dinosaur'] && hash['dinosaur']['root']
+      self
+    end
+    
+    # Generate a file using the given arguments
+    # @param klass [String,Class] what type of file to generate
+    # @param *params all other parameters to pass to the generator
+    def generate(klass,*params)
+      klass = generator_for_name(klass) if klass.is_a? String # if klass is a string, make sure it's a class
+      generator = klass.new(*params)
+      generator.generate
+      self
+    end
+    
+    def generated?(klass,*params)
+      klass = generator_for_name(klass) if klass.is_a? String
+      generator = klass.new(*params)
+      generator.generated?
+    end
+    
+    # Remove and reload an existing file
+    # @param klass [String,Class] what type of file to reload
+    # @param *params all other parameters to pass to the generator
+    def reload(klass,*params)
+      klass = generator_for_name(klass) if klass.is_a? String
+      generator = klass.new(*params)
+      generator.reload
+      self
+    end
+    
+    # Add a route to the Application routes file
+    # @param path [String] the new route's path
+    # @param controller [String] the name of the new route's controller
+    def route(path,controller)
+      klass = generator_for_name('Routes')
+      generator = klass.new
+      generator.route(path,controller)
+      self
+    end
+    
+    # Remove a rotue from the Application routes file
+    # @param path [String] the path to be deleted
+    def unroute(path)
+      klass = generator_for_name('Routes')
+      generator = klass.new
+      generator.unroute(path)
+      self
+    end
+    
+    # Remove a previously generated file
+    # @param klass [String,Klass] what kind of file to remove
+    # @param *params all other parameters to identify the file to be removed
+    def remove(klass,*params)
+      klass = generator_for_name(klass) if klass.is_a? String # if klass is a string, make sure it's a class
+      generator = klass.new(*params)
+      generator.remove
+      self
+    end
+    
+    # Find all routes set in the current Application
+    # @return [Hash] a Hash-map of each path to its corresponding controller
+    def routes
+      klass = generator_for_name('Routes')
+      generator = klass.new
+      generator.get_current_routes
+      generator.routes.dup
+    end
+    
+    # If the method name is of the type "generate_NAME(*params)",
+    # such as generate_javascript('contact','Display contact information'),
+    # call self.generate(NAME,*params), so
+    # self.generate('javascript','contact','Display contact information')
+    def method_missing(method_name,*params)
+      match = method_name.to_s.match /^generate_(\w+)$/
+      super unless match
+      type = match[1]
+      generate(type, *params)
+    rescue NameError => e # Couldn't load the proper constant
+      super
+    end
+    
+    # Remove the directory of this application
+    def destroy
+      FileUtils.rm_r dir
+      nil
+    end
+    
+    private
+    # Convert the names of generators to real Generator class objects
+    def generator_for_name(name)
+      name = name.split('_').map! { |str| "#{str[0].upcase}#{str[1,str.length-1]}" }.join('')
+      Ptero::Generator.const_get("#{name}Generator")
+    end
+
+    
+    
+    class << self
+      
+      # Create a new application with basic files and Composer dependencies. Yield the newly-created Application object to a block if one is given.
+      # @param name [String] the name of the new  application
+      # @param dir [String,Pathname] the directory in which to create the new application
+      # @return [Application] the new Application object
+      def create(name,dir=Pathname.new(Dir.pwd))
+        
+        Dir.chdir dir do
+          raise Ptero::Exception::ApplicationException, "Cannot create project #{name} because a file already exists with that name" if File.exist? name 
+        
+          puts "Creating directory #{name} in #{Dir.pwd}"
+          Dir.mkdir(name)
+          Dir.chdir(name) do
+            
+            puts "Loading default composer.json"
+            composer = JSON.parse( File.read("#{__dir__}/composer_default.json") )
+            composer[:dinosaur] = {
+              name: name,
+              root: true
+            }
+          
+            puts "Writing project composer.json"
+            File.open('composer.json','w') do |file|
+              file.puts JSON.pretty_generate(composer)
+            end
+          
+            puts "Initializing app"
+            app = app_for(Dir.pwd)
+          
+            yield app if block_given?
+          
+            return app
+          
+          end
+        end
+        
+      end
+      
+      # Return the first verified application in the specified directory or its parents
+      # @param dir [String,Pathname] the starting directory
+      # @return [Application] the verified Application object
+      def app_for(dir=Dir.pwd)
+        path = Pathname.new dir
+        path.realpath.ascend do |level|
+          app = self.new(level)
+          return app if app.verify
+        end
+        
+        raise Ptero::Exception::ApplicationException, "Couldn't find composer.json with dinosaur information in #{dir} or parent directories"
+      end
+      
+      # Return the verified Application object corresponding to Dir.pwd or its parent directories
+      # @return [Application] the Application object that represents the found verified application
+      def current_app
+        app_for Dir.pwd
+      end
+      
+    end
+  end
+end