Phoenix 1.3.0 released

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:
https://hexdocs.pm/phoenix/1.3.0-rc.3/contexts.html

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

97 Likes

Here is a link with info on a 1.3 release of the PragProg Phoenix book: https://forums.pragprog.com/forums/393/topics/14820

1 Like

Hi @chrismccord thanks for Phoenix! I’m using Phoenix 1.3.0-rc in an umbrella application.

My structure is:

foobar_umbrella
  - foobar
  - foobar_web

So within my Phoenix app, naming looks like, for example an API controller:

defmodule FoobarWeb.Web.Api.V1.ArticleController do
  ...
end

Since the MyApp.Web alias has been changed to MyAppWeb, does this mean code will look like?

use FoobarWebWeb, :controller

How do you recommend I approach this update?


Also, I’m using Phoenix from NPM to connect to my Phoenix Channels using websockets, can I update the package from npm to get v2 of the channel protocols?

1 Like

The module of your web app, would be FoobarWeb, with calls to use FoobarWeb, :controller

The package hasn’t been updated yet, but will for the final release. You can specify a path dep in your package.json or vendor it today.

4 Likes

Thanks Chris!

Question about naming tables: How will tables be named when two different contexts has very same schema with different fields but also with clashing ones? Should I avoid situations like this one by name them differently, have one big table or split them somehow?

Rest looks very, very promising. Thanks a lot!

If you have two database-backed schemas in different contexts that are entirely separate, but named the same, then you will need to give one of them a unique name. You can do this by passing the --table flag to the generator.

We would need to talk about your specific use case to say more, but please check out the new context guide which will give you ideas how to handle this kind of scenario. In the guide we create an authors table for author specific information for our CMS, rather than polluting our Account’s “users” table with author specific data.
https://hexdocs.pm/phoenix/1.3.0-rc.3/contexts.html

6 Likes

Thanks for Phoenix. Thanks turning all the criticisms about contexts nil. This project is something to be proud of.

5 Likes

Thanks, I passed only an imaginated example here. I’ll read guides carefully. Thanks again for the great work you’ve made with the core team for the Elixir society :slight_smile:

1 Like

Congrats and thanks to @chrismccord and the #phoenixframework team! Started playing with it for couple of weeks now… it looks pretty solid!

2 Likes

Great!

Just tried out the new installer, and here’s a quick note about the test directory structure (for people upgrading from rc.2):

  • test/web is now test/my_app_web
  • the module names are now MyAppWeb
  • the files in test/support (conn_case, etc.) also have the MyAppWeb name

Thanks for all the hard work everyone’s put in.

2 Likes

Awesome!!

In case it’s useful, you can see the changes to generated files between the two RC’s here: https://www.phoenixdiff.org/?source=1.3.0-rc.2&target=1.3.0-rc.3

Or, if you’re upgrading from 1.2, you can see that at https://www.phoenixdiff.org as well.

11 Likes

I quite liked the table namespacing. Going to miss it as default. :icon_sad:

mix phx.gen.html Accounts User users email:string --table accounts_users
3 Likes

Thanks to Chris and the team! been using 1.3.0 for personal projects and loving it so far. It took some time to wrap my head around the new folder structure, but it makes everything more clear :slight_smile:

2 Likes

Awesome work, Chris! Kudos to you, and to your team! Thank you!

1 Like

I’m not quite sure what this comment is aiming for. What kind of feedback are you after around this release?

1 Like

As promised, 1.3.0 has landed! Check out the officinal announcement here:

22 Likes