Solar Cli

November 1st, 2008 by Ray in Cookbook, Solar | Tags: Cookbook, php, Solar | 1 Comment

Overview

One of the nice things Solar has to offer is its CLI (Command Line Interface), which can be used to accomplish tasks that would otherwise eat up valuable time, such as creating applications, models, tests, documentation, and unit tests. In this entry, I will be showing you how to use the current (Solar v1.0.0 alpha2) CLI, detailing commands, available options, parameters, and usage examples. So make sure that you have a fresh pot of coffee and let’s get to it!

First Glance

Under a Solar system you will find an executable called solar, located in the script directory. For our example, let’s assume our Solar system is installed under /var/www/solar/. You will find the executable under the directory /var/www/solar/script/.

From the terminal, change directories to /var/www/solar/. Let’s go ahead and run the solar executable and examine what is returned.

$ ./script/solar
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
Solar command-line tool.
Usage: solar <command> <options> <params>
Try 'solar help' for a list of commands.

Here we can see what our include paths are, as well as the configuration file we are using. In a Solar system, Solar defaults to using Solar.config.php, the default configuration file.

You will also notice that the Solar CLI gives you the proper syntax to use, solar <command> <options> <params>. This is important so keep it in mind as we go along For now, let’s jump to the most basic command and the most helpful, help.

Help command

We can learn more about any command in the CLI by using the help command. The syntax for this is solar help <command> where command is the command we want to know more about. We can also get a list of available commands by typing solar help. Let’s give that a try, shall we?

$ ./script/solar help
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
Solar command-line tool.
Usage: solar <command> <options> <params>
Try 'solar help <command>' for help on a specific command.
Available commands are:
    base
    help
    make-app
    make-docs
    make-model
    make-tests
    make-vendor
    run-tests

Here are all of our available commands. You can ignore the base command since this is just the command in which all other commands extend and is of no value to us here.

Here is a quick break down of each command.

• base – Base class in which all commands extend. Not usable from the CLI!
• help – Returns command usage or a list of available commands.
• make-app – Generates a basic application or an application with BREAD functionality.
• make-docs – Generates package and API documentation files.
• make-model – Generates a model class from an SQL table.
• make-tests – Generates a test class (or set of classes) from a given class.
• make-vendor – Creates the appropriate directories and symlinks for a new project (also referred to as a vendor space).
• run-tests – Runs a series of tests or a single test.

Please note that all commands have the following available options:

• –config – Allows you to use a specific configuration file. Default is Solar.config.php.
• -V | –version – Returns version information.
• -v | –verbose – Displays verbose output when available.

Now that we have a general idea of the available commands and proper syntax, let’s talk about each one in depth.

Make-app

Make-app allows you to rapidly generate a simple generic application or a more complex application that supports BREAD functionality on the fly.

Help information

$ ./script/solar help make-app
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
--extends
:  Extends from this class name.
--model
:  Add this model class automatically.
--target
:  The target directory, typically the PEAR directory.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Extends
The name of the class that we want to extend. This is handy if you are using a base class in which all applications extend. Currently defaults to Solar_App_Base.

Model
Solar can auto generate an application with BREAD functionality when you specify a model to use. This adds functionality for browsing, reading, editing, adding, and deleting records from the database.

Target
Allows you to specify the target directory to generate the given application. Not needed if you are using a Solar system.

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

Let’s say we want to create a simple application that will extend our page controller (Solar_Controller_Page). For the examples that follow, our project will be named “Vendor.”

$ ./script/solar make-app --extends=Solar_Controller_Page Vendor_App_Hello

This generates a basic application named Hello. If you change your working directory to /var/www/solar/source/Vendor/App/Hello/ you should have the following structure:

• /Hello/Helper/
• /Hello/Layout/
• /Hello/Locale/
• /Hello/Locale/en_US.php
• /Hello/View/
• /Hello/View/index.php
• /Hello.php

Now, let’s kick it up a notch and generate an application that uses an existing model. In this case, we want an application called Blog, for blog posts. The model we are using is called Posts since blogs usually contain posts. In this example I am assuming that the model Posts has already been created.

$ ./script/solar make-app --extend=Solar_Controller_Page --model=Vendor_Model_Posts Vendor_App_Blog

This will create all of the actions and views for browsing, reading, editing, adding, and deleting blog posts from the database.

Here are the generated files and directories, found under /var/www/solar/source/Vendor/App/Blog/.

• /Blog/Helper/
• /Blog/Layout/
• /Blog/Locale/
• /Blog/Locale/en_US.php
• /Blog/View/
• /Blog/View/add.php
• /Blog/View/browse.php
• /Blog/View/delete.php
• /Blog/View/edit.php
• /Blog/View/read.php
• /Blog/View/_record.php
• /Blog.php

Make-docs

Make-docs allows you to quickly turn your inline comments into solid documentation, like phpDocumentor.

Help information

$ ./script/solar help make-docs
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--class-dir
:  Write class API docs to this directory.
--config
:  Use this configuration file when starting Solar.
--package-dir
:  Write package docs to this directory.
--source
:  The source directory, typically the PEAR directory.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Class-dir
The directory where class API documentation will be written to.

Package-dir
The directory where package documentation will be written to.

Source-dir
The directory where your project lives. Given the example we have been working with, this would be /var/www/solar/source/vendor/.

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

Let’s say we have an application called Blog and we wanted to generate documentation for it. It is as easy as doing the following.

$ ./script/solar make-docs --class-dir=/var/www/solar/source/vendor/docs/ --package-dir=/var/www/solar/source/vendor/docs/ --source=/var/www/solar/source/vendor/ Vendor_App_Blog

If you take a look at the docs directory, /var/www/solar/source/vendor/docs/, you will see a file and a folder with the same name, Vendor_App_Blog. The file in this directory contains the package information and the directory contains many files, each file containing information about each relevant method for our application.

Make-model

Make-model reduces the time it takes to set up models, which can be very time consuming to setup by hand. Make-model streamlines this process by reading your existing SQL table and creating the model based off of this information.

Help information

$ ./script/solar help make-model
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--adapter
:  The SQL adapter class to use.
--config
:  Use this configuration file when starting Solar.
--connect
:  Connect to the database and fetch cols for the model setup.
--extends
:  Extend the model class from this parent class name.
--host
:  The host for the database connection.
--name
:  The name of the database to connect to.
--pass
:  The password for the database connection.
--port
:  The port for the database connection.
--table
:  The table name for the model to use.
--target
:  Write files to this directory, typically the include directory.
--user
:  The username for the database connection.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Adapter
The SQL adapter to use. Examples include Solar_Sql_Adapter_Mysql and Solar_Sql_Adapter_Sqlite.

Connect
If set to true, Solar connects to the SQL table to generate the model to reflect the columns in the table.

Extends
The name of the class that we want to extend. Defaults to Solar_Sql_Model.

Host
The host where the database resides (e.g. localhost).

Name
Name of the database to connect to.

Pass
Password to be used with user name.

Port
Port that our database is running on.

Table
Table name we want to create our model for and from.

User
User name that has access to the database table.

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

Now, this is where using a configuration file makes life easy. First though, I am going to show you the (more time consuming) way to generate a model without changing your current (default) configuration file.

Just so I do not lose you, let me specify the basic settings I am using for my database.

• Database type: MySQL
• Database name: vendor
• Host: localhost
• User name: root
• Password: s3cr3tP@ssw0rd

Now let’s generate a model that controls blog posts. The name of this model will be posts. The table layout we will be using looks like this:

• id (primary key, auto increment)
• title (varchar(100))
• body (text)
• author (varchar(100))
• created (datetime)
• updated (datetime)

For the lazy people reading this, you can just run the following MySQL to generate the table.

CREATE TABLE posts(
id INT NOT NULL AUTO_INCREMENT,
PRIMARY KEY(id),
    title VARCHAR(100),
    body VARCHAR(100),
    author VARCHAR(100),
    created DATETIME,
    updated DATETIME
) engine=INNODB

Now on to generating our model for posts (the long way).

$ ./source/solar make-model --adapter=Solar_Sql_Adapter_Mysql --connect=true --host=localhost --name=vendor --pass=s3cr3tP@ssw0rd --table=posts --user=root Vendor_Model_Posts

That is all there is to it. You can see the files generated by changing directories to /var/www/solar/source/vendor/Vendor/Model/. Here you will see the following layout.

• /Posts.php
• /Posts/Collection.php
• /Posts/Record.php
• /Posts/Setup
• /Posts/Setup/table_cols.php
• /Posts/Setup/table_name.php

Now, the easy way to generate models is to save your database connection information to your configuration file. Go ahead and open up Solar.config.php, located under the directory /var/www/solar/config/.

Add the following to the configuration file.

$config['Solar_Sql']['adapter'] = 'Solar_Sql_Adapter_Mysql';
$config['Solar_Sql_Adapter_Mysql'] = array(
    'host' = 'localhost',
    'user' = 'root',
    'pass' = 's3cr3tP@ssw0rd',
    'name' = 'vendor',
);

Now, when we want to generate a model, we only need to do the following.

$ ./script/solar make-model --table=posts Vendor_Model_Posts

Make-tests

Make-tests is great for generating a single set or suite of tests that can (and should) be altered to test your classes.

Help information

$ ./script/solar help make-tests
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
--only
:  Make tests only for the named class; do not descend into subdirectories.
--target
:  Where the tests will be written to.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Only
Make tests only for the specified class (e.g. Vendor_App_Blog only).

Target
The directory where the test files will be saved to. Defaults to the tests directory, /var/www/solar/source/vendor/tests/ for our example(s).

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

To generate a suite of tests for your classes, you need only to specify the target to save the tests to and the class in which you want to generate the tests for.

$ ./script/solar make-tests --target=/var/www/solar/source/vendor/tests/ Vendor_App_Blog

We are left with the the following directory structure under the tests directory, /var/www/solar/source/vendor/tests/.

• /Test/Vendor/
• /Test/Vendor/App/
• /Test/Vendor/App/Blog.php

At this point you will want to edit Blog.php to edit the predefined tests for your class.

If you only need to generate a test for a specific class and you do not want to recursively create tests, issue the only option.

$ ./script/solar make-tests --only=true --target=/var/www/solar/source/vendor/tests/ Vendor_App_Blog

Make-vendor

Make-vendor generates the most basic vendor space for a new project. Before any application, model, etc. can be created, a vendor must be created.

Help information

$ ./script/solar help make-vendor
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

None

Available params

Name
The vendor name. This is required. An example could be Vendor.

Usage examples

To create a new vendor, simply do the following.

$ ./script/solar make-vendor Vendor

The following directories are generated.

• /source/vendor/bin/
• /source/vendor/docs/
• /source/vendor/tests/
• /source/vendor/Vendor/App/
• /source/vendor/Vendor/App/Public/
• /source/vendor/Vendor/App/Public/images/
• /source/vendor/Vendor/App/Public/scripts/
• /source/vendor/Vendor/App/Public/styles/
• /source/vendor/Vendor/Model/
• /source/vendor/Vendor/Locale/
• /source/vendor/Vendor/View/
• /source/vendor/Vendor/View/Helper/

And the following symlinks (*nix only) are made.

• /source/vendor/Vendor/ to /include/Vendor
• /source/vendor/Vendor/App/Public/ to /docroot/public/Vendor/
• /source/solar/bin/solar to /script/vendor

Run-tests

Run-tests allows you to run the tests generated by make-tests.

Help information

$ ./script/solar help run-tests
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
--dir
:  The path to the tests directory.
--only
:  Run only the named test class; do not descend into subclass tests.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Dir
The directory where the tests are held.

Only
Run a specific test class without descending into subclass tests.

Available params

None

Usage examples

In the usage example for make-tests shown above, we created a test class for our Blog application, Vendor_App_Blog. If we wanted to run this test all we would have to do is the following.

$ ./script/solar run-tests --dir=/var/www/solar/source/vendor/tests/

Note that if there are other tests in the tests directory those will be run as well. If we only want to run a specific test we would use the only option.

$ ./script/solar --dir=/var/www/solar/source/vendor/tests/Test/Vendor/App/Blog.php --only=true

---