cypresslab / compass-elephant
A library to manage a compass project with PHP
Installs: 108 037
Dependents: 2
Suggesters: 0
Security: 0
Stars: 8
Watchers: 2
Forks: 6
Open Issues: 0
Requires
- php: >=5.3.3
- symfony/finder: ~2.1
- symfony/process: ~2.1
Requires (Dev)
- phpunit/phpunit: ~4.3
README
A wrapper for the compass binary written in PHP
Requirements
- php >= 5.3
- *nix system with compass installed
Dependencies
for tests
Installation
composer
To install CompassElephant with composer you simply need to create a composer.json in your project root and add:
{ "require": { "cypresslab/compass-elephant": ">=0.1.0" } }
Then run
$ wget -nc http://getcomposer.org/composer.phar $ php composer.phar install
You have now CompassElephant installed in vendor/cypresslab/compasselephant
And an handy autoload file to include in you project in vendor/.composer/autoload.php
pear
Add the Cypresslab channel
$ pear channel-discover pear.cypresslab.net
And install the package. By now CompassElephant is in alpha state. So remember the -alpha in the library name
$ pear install cypresslab/CompassElephant-alpha
On Cypresslab pear channel homepage you can find other useful information
Testing
The library is fully tested with PHPUnit.
Go to the base library folder and run the test suites
$ phpunit
Code style
- CompassElephant follows the Symfony2 Coding Standard
- I'm using gitflow so, if you want to contribute, please send a pull-request on develop branch
How to use
Remember to give the user the right permissions to access the filesystem. If you are using a web server give permissions to both your user and the web server user.
constructor
<?php $project = new CompassProject("/path/to/compass"); // create the base class, only the path is mandatory.... // Here is a full customized project $path = "/path/to/compass"; $name = "blog"; // a project name. Not used in the library...but useful if you have more than one project $binary = new CompassBinary('/usr/local/bin/compass'); // use this to set a custom path for the executable. If blank the library try with "which compass" before showing an error $stalenessChecker = 'finder'; // or native. More on this later $configFile = 'config_prod.rb'; // the name of the ruby config file. Defaults to config.rb $autoInit = false; // if true, when given a folder without a config file inside, CompassElephant will try to initialize a compass project $project = new CompassProject($path, $name, $binary, $stalenessChecker, $configFile, $autoInit); // Here is the full constructor signature /** * Class constructor * * @param string $projectPath the path to the compass project * @param null $name the project name * @param \CompassElephant\CompassBinary|null $compassBinary a CompassBinary instance * @param mixed $stalenessChecker a StalenessCheckerInterface instance * @param string $configFile the compass config file name * @param bool $autoInit whether to call init() on an empty folder project * * @internal param \CompassElephant\CommandCaller $commandCaller a CommandCaller instance */ public function __construct($projectPath, $name = null, CompassBinary $compassBinary = null, $stalenessChecker = null, $configFile = 'config.rb', $autoInit = true) { // ... }
manage a compass project
<?php // if the project do not contains a config file, CompassElephant assumes it isn't initialized. See autoInit parameters for skip this step if (!$project->isInitialized()) { $project->init(); // call the "compass create" command } // return false if the project needs to be recompiled. In other words if you changed something in config.rb, sass or scss files after the last sylesheets generation if (!$project->isClean()) { $project->compile(); // compile the project echo $project->isClean(); // return true now }
Staleness Checker
Compass checks if the project need to be compiled in two different ways:
finder This method uses the awesome Symfony Finder component. It parse the config.rb file for the sass path and for the stylesheet path. Then check if the modification time of the stylesheets comes before the modification of the config file or a sass file. This is the default method.
native uses the command "compass compile --dry-run" and parse the output to see if there are stylesheets not aligned with sass. This method is not so cool because it's really slow. Even by using it only in a dev environment, it adds 400-500 ms of overhead on every check. So use it only if you can't use the finder method
Are you reinventing the wheel?
I use Assetic for my assets...and you should use it too.
But for now the Compass implementation do not work as intended. Assetic is built upon the concept of a single asset compiled. And it's not aware of dependencies
A pull request for assetic is not so easy, because it should change the entire structure of the library. And I know that the author is working on it.
I promise that, when the issue will be adressed, I will delete this library and return to Assetic. By now you can (should) use it to rewrite/uglify the stylesheets generated by CompassElephant. And this is exactly what I'm doing now.
Symfony2
CompassElephantBundle let symfony do the work for you