Hey folks,

Phoenix 1.3.0 is out! The final release please brings tweaks to web directory and alias conventions that were estabished in the first 1.3 RC, as well as a V2 channel wire-protocol.

If you are just tuning in for the first time on Phoenix 1.3 details, check out the rc.0 annoncement for background on the final release: Phoenix v1.3.0-rc.0 released

To use the new phx.new project generator, you can install the archive with the following command:

$ mix archive.install https://github.com/phoenixframework/archives/raw/master/phx_new.ez

Directory Changes

The “web” directory has been moved from lib/my_app/web, to lib/my_app_web. This change makes a clearer separation between your greater Elixir application and the web interface to it. The new convention also aligns more closely to the umbrella application structure, so it will be a more natural step to go from a single application to an umbrella application in the future. For example, the new structure produced by mix phx.new looks as follows:

lib
├── my_app
│   ├── application.ex
│   └── repo.ex
├── my_app.ex
└── my_app_web
|   ├── channels
|   ├── controllers
|   ├── endpoint.ex
|   ├── gettext.ex
|   ├── router.ex
|   ├── templates
|   ├── views
└── my_app_web.ex

Web alias changes

The MyApp.Web alias has been renamed to MyAppWeb. This removes a special-case naming convention we had that went against common Elixir conventions when it comes to naming umbrella applications. With this change, we now have parity with Elixir naming, with the added bonus that a unique namespace further signals the separation of your greater Elixir application and business logic from your Phoenix web tier.

New Channel V2 wire protocol

rc.3 also includes a backwards-compatible, V2 of our channel wire protocol. The new protocol resolves a race condition that was discovered under some messaging circumstances. The new format also includes improved data compaction when serializing. The updated phoenix.js client will use V2, but older clients unable to speak the new protocol will contiune to work as before.

Dynamic Endpoint config changes

The rc.0-2 on_init configuration is no longer supported. Instead of on_init, add the load_from_system_env: true to your endpoint config, then define an init/2 clause in your endpoint module. For example:

config :my_app, MyAppWeb.Endpoint,
  ...,
  load_from_system_env: true,

and then in your endpoint:

@doc """
  Callback invoked for dynamically configuring the endpoint.

  It receives the endpoint configuration and checks if
  configuration should be loaded from the system environment.
  """
  def init(_key, config) do
    if config[:load_from_system_env] do
      port = System.get_env("PORT") || raise "expected the PORT environment variable to be set"
      {:ok, Keyword.put(config, :http, [:inet6, port: port])}
    else
      {:ok, config}
    end
  end

Context Generator changes

The mix phx.gen.html|json|context generators no longer namespace tables by the context name, preferring to simply name the table after the given resource. After feedback from the previous RC’s, it was clear the prefix was a source of confusion and could be more difficult to maintain.

Context Guide and HexDocs powered Phoenix Guides

We are also nearing completion of our 1.3.0 guides overhaul, including the new context guide, which can be read here:

With the 1.3.0 release, we are moving off of readme.io for guide hosting and hosting all guides on hexdocs.pm. This allows us to share our ex_doc documentation for phoenix itself with the guides – enabling true cross-references between source docs and guides, as well as effortlessly versioned guides. Some formatting still needs to be addressed on the guides, but check them out on hexdocs and let us know what you think.

Thanks!

Chris