Upgrading your Phoenix 0.5.x application to 0.6.0

gistfile1.md

Upgrading Phoenix 0.5.x to 0.6.0

If you're still on 0.4.x, follow [this 0.4x to 0.5.0 upgrade guide] (http://learnelixir.com/blog/2014/10/29/migrating-applications-from-phoenix-0-dot-4-1-to-phoenix-0-dot-5-0/), then head back over here.

Phoenix 0.6.0 brings some nice enhancements and a few backwards incompatible changes. The following steps should get your 0.5.x apps up and running on the latest and greatest.

Router

The Router no longer defines the default :browser and :api pipelines for you, but they remain the idiomatic defaults. You can copy the standard pipelines into your router:

defmodule MyApp.Router do
  use Phoenix.Router

  pipeline :browser do
    plug :accepts, ~w(html)
    plug :fetch_session
  end

  pipeline :api do
    plug :accepts, ~w(json)
  end
  ...
end

Main App View

Rename your main MyApp.Views to the singular MyApp.View, and restructure the contents according to this example:

0.5.x

defmodule <%= application_module %>.Views do

  defmacro __using__(_options) do
    quote do
      use Phoenix.View
      import unquote(__MODULE__)

      # This block is expanded within all views for aliases, imports, etc
      import <%= application_module %>.I18n
      import <%= application_module %>.Router.Helpers
      alias Phoenix.Controller.Flash
    end
  end

  # Functions defined here are available to all other views/templates
end

0.6.0

• Your main view now use's Phoenix.View directly
• defmacro __using__ is replaced by a new using macro that accepts quoted expression. Should be a copy/paste from your 0.5.x using block.

defmodule MyApp.View do
  use Phoenix.View, root: "web/templates"

  # The quoted expression returned by this block is applied
  # to this module and all other views that use this module.
  using do
    quote do
      # Import common functionality
      import MyApp.I18n
      import MyApp.Router.Helpers

      # Use Phoenix.HTML to import all HTML functions (forms, tags, etc)
      use Phoenix.HTML

      # Common aliases
      alias Phoenix.Controller.Flash
    end
  end

  # Functions defined here are available to all other views/templates
end

Controllers

• You can now set your template layouts with the put_layout function in the controller. This funtion also composes really nicely as a plug.
• render template string arguments has changed, see below actions for examples
  • When using a string template name, the extension is now required
  • A symbol template name can be used for 0.5.x behavior, where the extension is chosen automatically by resp_content_type
  • Using :within was renamed in favor of :layout for rendering with layouts
• redirect(conn, url) was deprecated in favor of redirect(conn, to: url) for 'local' redirects, and redirect(conn, external: url) for external redirects.

defmodule MyApp.MyController do
  use Phoenix.Controller
  
  plug :put_layout, "checkout.html"
  plug :action

  def show(conn, _) do
    # When using a string template name, the extension is now required
    render conn, "show.html"
  end
  
  def index(conn, _) do
    # A symbol template name can be used for `0.5.x` behavior, where the extension is chosen 
    # automatically by resp_content_type
    render conn, :index
  end
  
  def another_action(conn, _) do
    # `put_layout` can be used directly to override/set layout within actions
    conn
    |> put_layout("bare.html")
    |> render("index.html")
  end
end

PubSub

Phoenix.Topic has been renamed to Phoenix.PubSub. If you were calling into the topic layer directly, update your module references.