Merge pull request #50 from capistrano/next

1.0.0.rc1 - Symfony 3 directory structure

Author: peterjmit

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Capistrano Symfony 1.x Changelog
+
+
+## `1.0.0.rc1`
+
+https://github.com/capistrano/symfony/compare/0.4.0...1.0.0.rc1
+
+* Use file permissions gem v1
+* Symfony 3 directory structure is on by default
+* Remove `use_set_permission` variable
+* Remove `web/uploads` as a default linked directory
+* Remove support for Assetic (see: https://github.com/symfony/symfony-standard/pull/860)
+* Support SensioLabsDistributionBundle 5 (#49)
+* Support Symfony 3 directory structure (#31)
+* `build_bootstrap_path` is now a DSL method
+* `symfony_console` is now a DSL method (use instead of `invoke "symfony:console"`)
+* Paths DSL file has been moved to `lib/capistrano/dsl/symfony.rb`
+* Deprecated `symfony:command` task has been removed
+* `webserver_user` variable has been removed (#40)
+* Various typo fixes
+
+### Contributors
+
+Thanks to everyone who has filed an issue or submitted a fix
+
+  * @kriswallsmith
+  * @zaerl
+  * @sandermarechal
+  * @pborreli
+  * @wideawake
+  * @issei-m
+  * @alafon

README.md

@@ -1,7 +1,6 @@
 # Capistrano::Symfony
 
-Symfony 2 (standard edition) specific tasks for Capistrano v3
-(inspired by [capifony][2])
+Symfony 2 (standard edition) specific tasks for Capistrano v3 (inspired by [capifony][2]).
 
 It leverages the following capistrano tasks to deploy a Symfony app
 
@@ -12,8 +11,8 @@ It leverages the following capistrano tasks to deploy a Symfony app
 
 ```
 # Gemfile
-gem 'capistrano',  '~> 3.1'
-gem 'capistrano-symfony', '~> 0.1', :github => 'capistrano/symfony'
+gem 'capistrano',  '~> 3.4'
+gem 'capistrano-symfony', '~> 1.0.0.rc1'
 ```
 
 ## Usage
@@ -25,79 +24,74 @@ Require capistrano-symfony in your cap file
 require 'capistrano/symfony'
 ```
 
+
 ### Settings
 
-capistrano-symfony exposes the following settings (displayed with defaults):
+If you are using an un-modified symfony-standard edition, version 3 then you do not need to change/add anything to your `deploy.rb` other than what is required from Capistrano.
+
+We do however expose the following settings (shown with default evaluated values) that can be modified to suit your project. Please refer to `lib/capistrano/symfony/defaults.rb` to see exactly how the defaults are set up.
+
 
 ```ruby
-# Symfony environment
+# Symfony console commands will use this environment for execution
 set :symfony_env,  "prod"
 
-# Symfony application path
-set :app_path,              "app"
-
-# Symfony web path
-set :web_path,              "web"
+# Set this to 2 for the old directory structure
+set :symfony_directory_structure, 3
+# Set this to 4 if using the older SensioDistributionBundle
+set :sensio_distribution_version, 5
 
-# Symfony log path
-set :log_path,              fetch(:app_path) + "/logs"
+# symfony-standard edition directories
+set :app_path, "app"
+set :web_path, "web"
+set :var_path, "var"
+set :bin_path, "bin"
 
-# Symfony cache path
-set :cache_path,            fetch(:app_path) + "/cache"
+# The next 3 settings are lazily evaluated from the above values, so take care
+# when modifying them
+set :app_config_path, "app/config"
+set :log_path, "var/logs"
+set :cache_path, "var/cache"
 
-# Symfony config file path
-set :app_config_path,       fetch(:app_path) + "/config"
+set :symfony_console_path, "bin/console"
+set :symfony_console_flags, "--no-debug"
 
-# Controllers to clear
+# Remove app_dev.php during deployment, other files in web/ can be specified here
 set :controllers_to_clear, ["app_*.php"]
 
-# Files that need to remain the same between deploys
-set :linked_files,          []
-
-# Dirs that need to remain the same between deploys (shared dirs)
-set :linked_dirs,           [fetch(:log_path), fetch(:web_path) + "/uploads"]
-
-# Dirs that need to be writable by the HTTP Server (i.e. cache, log dirs)
-set :file_permissions_paths,         [fetch(:log_path), fetch(:cache_path)]
-
-# Name used by the Web Server (i.e. www-data for Apache)
-set :file_permissions_users, ['www-data']
-
-# Name used by the Web Server (i.e. www-data for Apache)
-set :webserver_user,        "www-data"
-
-# Method used to set permissions (:chmod, :acl, or :chgrp)
-set :permission_method,     false
-
-# Execute set permissions
-set :use_set_permissions,   false
-
-# Symfony console path
-set :symfony_console_path, fetch(:app_path) + "/console"
+# asset management
+set :assets_install_path, "web"
+set :assets_install_flags,  '--symlink'
 
-# Symfony console flags
-set :symfony_console_flags, "--no-debug"
+# Share files/directories between releases
+set :linked_files, []
+set :linked_dirs, ["var/logs"]
 
-# Assets install path
-set :assets_install_path,   fetch(:web_path)
+# Set correct permissions between releases, this is turned off by default
+set :file_permissions_paths, ["var"]
+set :permission_method, false
+```
 
-# Assets install flags
-set :assets_install_flags,  '--symlink'
+#### Using this plugin with the old Symfony 2 directory structure and SensioDistributionBundle <= 4
 
-# Assetic dump flags
-set :assetic_dump_flags,  ''
+Add the following to `deploy.rb` to use the old directory structure
 
-fetch(:default_env).merge!(symfony_env: fetch(:symfony_env))
+```
+# deploy.rb
+set :symfony_directory_structure, 2
+set :sensio_distribution_version, 4
 ```
 
+If you are upgrading this gem and have modified `linked_dirs` or "advanced" variables such as `log_path` then you will need to update those accordingly
+
 ### Flow
 
 capistrano-symfony hooks into the [flow][1] offered by capistrano. It adds to that flow like so
 
-* ```symfony:create_cache_dir```
-* ```symfony:set_permissions```
-* ```symfony:cache:warmup```
-* ```symfony:clear_controllers```
+* `symfony:create_cache_dir`
+* `symfony:set_permissions`
+* `symfony:cache:warmup`
+* `symfony:clear_controllers`
 
 ```
 deploy
@@ -125,16 +119,38 @@ deploy
     |__ deploy:log_revision
 ```
 
+### File permissions
+
+Set the `permission_method` variable to one of `:chmod`, `:acl`, or `:chgrp` in your `deploy.rb` to handle the common scenario of a web user and the deploy user being different.
+
+Both will need access to the files/directories such as `var/cache` and `web/uploads` (if you handle uploads). Set `file_permissions_users` to your webserver user
+
+Example:
+
+```
+# deploy.rb
+
+set :permission_method, :acl
+set :file_permissions_users, ["nginx"]
+set :file_permissions_paths, ["var", "web/uploads"]
+```
+
+Please note that `:acl` requires that `setfacl` be available on your deployment target
+
+See [the symfony documentation](http://symfony.com/doc/current/book/installation.html#checking-symfony-application-configuration-and-setup) and [the file permission capistrano plugin](https://github.com/capistrano/file-permissions) for reference
+
 ### Integrated common tasks
 
-The folowing common tasks are already integrated:
-* ```symfony:assets:install```
-* ```symfony:assetic:dump```
+The following common tasks are available:
+
+* `symfony:assets:install`
+* `symfony:build_bootstrap` - useful if you disable composer
+
+So you can use them with hooks in your project's `deploy.rb` like this:
 
-So you can use them with hooks like this:
 ```ruby
-  after 'deploy:updated',   'symfony:assets:install'
-  after 'deploy:updated',   'symfony:assetic:dump'
+after 'deploy:updated', 'symfony:assets:install'
+before 'deploy:updated', 'symfony:build_bootstrap'
 ```
 
 ### Using the Symfony console
@@ -148,17 +164,19 @@ project you may want to run migrations during a deploy.
 ```ruby
 namespace :deploy do
   task :migrate do
-    invoke 'symfony:console', 'doctrine:migrations:migrate', '--no-interaction'
+    symfony_console('doctrine:migrations:migrate', '--no-interaction')
   end
 end
 ```
 
-You can also apply role filter on your commands by passing a fourth parameter.
+If you want to execute a command on a host with a given role you can use the Capistrano `on` DSL, additionally using `within` from Capistrano will change the directory
 
 ```ruby
 namespace :deploy do
   task :migrate do
-    invoke 'symfony:console', 'doctrine:migrations:migrate', '--no-interaction', 'db'
+    on roles(:db) do
+      symfony_console('doctrine:migrations:migrate', '--no-interaction')
+    end
   end
 end
 ```

capistrano-symfony.gemspec

@@ -4,11 +4,11 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |gem|
   gem.name          = "capistrano-symfony"
-  gem.version       = '0.4.0'
+  gem.version       = '1.0.0.rc1'
   gem.authors       = ["Peter Mitchell"]
   gem.email         = ["pete@peterjmit.com"]
   gem.description   = %q{Symfony specific Capistrano tasks}
-  gem.summary       = %q{Capistrano Symfony - Easy deployment of Symfony 2 apps with Ruby over SSH}
+  gem.summary       = %q{Capistrano Symfony - Easy deployment of Symfony 2 & 3 apps with Ruby over SSH}
   gem.homepage      = "http://github.com/capistrano/capistrano-symfony"
 
   gem.files         = `git ls-files`.split($/)
@@ -31,5 +31,5 @@ eos
 
   gem.add_dependency 'capistrano', '~> 3.1'
   gem.add_dependency 'capistrano-composer', '~> 0.0.3'
-  gem.add_dependency 'capistrano-file-permissions', '~> 0.1.0'
+  gem.add_dependency 'capistrano-file-permissions', '~> 1.0'
 end

lib/capistrano/dsl/symfony.rb

@@ -0,0 +1,57 @@
+module Capistrano
+  module DSL
+    module Symfony
+
+      def symfony_app_path
+          release_path.join(fetch(:app_path))
+      end
+
+      def symfony_web_path
+          release_path.join(fetch(:web_path))
+      end
+
+      def symfony_bin_path
+        release_path.join(fetch(:bin_path))
+      end
+
+      def symfony_var_path
+        release_path.join(fetch(:var_path))
+      end
+
+      def symfony_log_path
+          release_path.join(fetch(:log_path))
+      end
+
+      def symfony_cache_path
+          release_path.join(fetch(:cache_path))
+      end
+
+      def symfony_config_path
+          release_path.join(fetch(:app_config_path))
+      end
+
+      def symfony_console_path
+          release_path.join(fetch(:symfony_console_path))
+      end
+
+      def symfony_vendor_path
+        release_path.join('vendor')
+      end
+
+      def build_bootstrap_path
+        bootstrap_path = symfony_vendor_path.join("sensio/distribution-bundle")
+
+        if fetch(:sensio_distribution_version).to_i <= 4
+          bootstrap_path = bootstrap_path.join("Sensio/Bundle/DistributionBundle")
+        end
+
+        bootstrap_path.join("Resources/bin/build_bootstrap.php")
+      end
+
+      def symfony_console(command, params = '')
+        execute :php, symfony_console_path, command, params, fetch(:symfony_console_flags)
+      end
+
+    end
+  end
+end

lib/capistrano/symfony.rb

@@ -1,6 +1,10 @@
+require "capistrano/dsl/symfony"
+self.extend Capistrano::DSL::Symfony
+
+SSHKit::Backend::Netssh.send(:include, Capistrano::DSL::Symfony)
+
 require "capistrano/file-permissions"
 require "capistrano/composer"
-require "capistrano/symfony/dsl"
 require "capistrano/symfony/symfony"
 
 # Core tasks for deploying symfony