Phoenix

Elixir Web Framework targeting full-featured, fault tolerant applications with realtime functionality

Build Status

Getting started

  1. Install Phoenix 

     git clone https://github.com/phoenixframework/phoenix.git && cd phoenix && mix do deps.get, compile

  2. Create a new Phoenix application 

     mix phoenix.new your_app /path/to/scaffold/your_app

    Important: Run this task in the Phoenix installation directory cloned in the step above. The path provided: /path/to/scaffold/your_app/ should be outside of the framework installation directory. This will either create a new application directory or install the application into an existing directory.

    #### Examples: 

     mix phoenix.new your_app /Users/you/projects/my_app
 mix phoenix.new your_app ../relative_path/my_app

  3. Change directory to /path/to/scaffold/your_app. Install dependencies and start web server 

     mix do deps.get, compile
 mix phoenix.start

Router example

defmodule YourApp.Router do
  use Phoenix.Router

  plug Plug.Static, at: "/static", from: :your_app

  get "/pages/:page", Controllers.Pages, :show, as: :page
  get "/files/*path", Controllers.Files, :show

  resources "users", Controllers.Users do
    resources "comments", Controllers.Comments
  end

  scope path: "admin", alias: Controllers.Admin, helper: "admin" do
    resources "users", Users
  end
end

Controller examples

defmodule Controllers.Pages do
  use Phoenix.Controller

  def show(conn) do
    if conn.params["page"] in ["admin"] do
      redirect conn, Router.page_path(page: "unauthorized")
    else
      text conn, "Showing page #{conn.params["page"]}"
    end
  end

end

defmodule Controllers.Users do
  use Phoenix.Controller

  def show(conn) do
    text conn, "Showing user #{conn.params["id"]}"
  end

  def index(conn) do
    html conn, """
    <html>
      <body>
        <h1>Users</h1>
      </body>
    </html>
    """
  end
end

Configuration

Phoenix provides a configuration per environment set by the MIX_ENV environment variable. The default environment Dev will be set if MIX_ENV does not exist.

Configuration file structure:

├── your_app/lib/config/
│   ├── config.ex          Base application configuration
│   ├── dev.ex
│   ├── prod.ex
│   └── test.ex
# your_app/lib/config/config.ex
defmodule YourApp.Config do
  use Phoenix.Config.App

  config :router, port: System.get_env("PORT")
  config :plugs, code_reload: false
  config :logger, level: :error
end

# your_app/lib/config/dev.ex
defmodule YourApp.Config.Dev do
  use YourApp.Config

  config :router, port: 4000
  config :plugs, code_reload: true
  config :logger, level: :debug
end

Mix Tasks

mix phoenix                                    # List Phoenix tasks
mix phoenix.new     app_name destination_path  # Creates new Phoenix application
mix phoenix.routes  [MyApp.Router]             # Prints routes
mix phoenix --help                             # This help

Static Assets

Static asset support can be added by including Plug.Static in your router. Static assets will be served from the priv/static/ directory of your application.

  plug Plug.Static, at: "/static", from: :your_app

Documentation

API documentaion is available at http://api.phoenixframework.org/

Development

There are no guidelines yet. Do what feels natural. Submit a bug, join a discussion, open a pull request.

Building documentation

  1. Clone docs repository into ../docs. Relative to your phoenix directory.
  2. Run mix run release_docs.exs in phoenix directory.
  3. Change directory to ../docs.
  4. Commit and push docs.

Feature Roadmap