This documentation is best viewed at [ash-hq.org](https://ash-hq.org)
<!--- ash-hq-hide-stop --><!----->
## Who is This For?
This is designed to be a quick start guide for Ash with Phoenix. Familiarity with Phoenix and LiveView are not necessary, but would certainly be helpful.
## Goals
In this guide we will:
1. Create a new Phoenix project
2. Setup Ash, AshPhoenix and AshPostgres as dependencies
If you want to follow along yourself, you will need the following things:
1. Elixir (1.12 or later) and Erlang (22 or later) installed
2. PostgreSQL installed
3. A text editor
4. A terminal to run the examples
## Setup
### Create a New Phoenix Project
_This section is based on the [Phoenix installation docs](https://hexdocs.pm/phoenix/installation.html). For more details go there._
First we need to install the Phoenix project generator, then we'll run the generator to create our new project.
**NOTE: DO NOT run `mix ecto.create`, (as it asks you to) we will do this the Ash way later.**
```bash
# install Phoenix project generator
$ mix archive.install hex phx_new
# generate Phoenix project
$ mix phx.new my_ash_phoenix_app
# cd into project
$ cd my_ash_phoenix_app
```
### Add Dependencies
We now need to add Ash, AshPhoenix and AshPostgres to our Phoenix project. We need to add the dependencies to the `deps` function in our `mix.exs`. We'll also need to add dependencies to our `.formatter.exs` to ensure consistent formatting when using `mix format`.
Now in the terminal install these new dependencies.
```bash
$ mix deps.get
```
### Use `AshPostgres.Repo`
We need to swap `Ecto.Repo` for `AshPostgres.Repo`. `AshPostgres.Repo` enriches your repo with additional AshPostgres specific behaviour, but is essentially a thin wrapper around `Ecto.Repo`.
To use `AshPostgres.Repo` change your repo module to look like this:
```elixir
# lib/my_ash_phoenix_app/repo.ex
defmodule MyAshPhoenixApp.Repo do
use AshPostgres.Repo, otp_app: :my_ash_phoenix_app
# Installs Postgres extensions that ash commonly uses
We need to specify the Ash domains that our application uses and some config for backwards compatibility that will be removed in the next major release.
An Ash domain can be thought of as a [Bounded Context](https://martinfowler.com/bliki/BoundedContext.html) in Domain Driven Design terms and can seen as analogous to a Phoenix context. Put simply, its a way of grouping related resources together. In our case our domain will be called `MyAshPhoenixApp.Blog`.
An Ash domain points to Ash resources. An Ash domain can point to one or more resources. In our case we will only have a single resource `MyAshPhoenixApp.Blog.Post`. We'll be taking a deeper look into that in the next section.
A resource is a central concept in Ash. In short, a resource is a domain model object in your system. A resource defines the data it holds and defines the actions that can operate on that data.
It's convention to place all the resource in their own resources folder. So when we create `Post` we will place it in `lib/my_ash_phoenix_app/blog/resources/post.ex`. So the structure after making the resource should look like so:
Now we need to populate our database. We do this by generating and performing a migration.
We can use a generator to produce a migration for us. Ash can deduce what needs to go into the migration and do the hard work for us, to do this use the command below:
**All interaction with your resource attributes always occur through an action**. In our resource we are using the default actions for `:create, :read, :update, :destroy` along with a custom action `:by_id`.
`:create` and `:update` and `:destroy` actions require a changeset. Ash changesets are conceptually similar to [Ecto changesets](https://hexdocs.pm/ecto/Ecto.Changeset.html). They're data structures which represent an intended change to an Ash resource and provide validation.
The `:read` action takes a query instead of a changeset.
Below is the most verbose way of calling your resource. All other ways of interaction are some kind of shorthand of these. This means at some point a changeset is being created and passed to the domain, even if it's encapsulated within another function.
As stated above, this is verbose so Ash has a built in shortcut - The `code_interface`. You may notice this has already been done in your `Post` resource. Here it is again with more explanation:
```elixir
code_interface do
# defining function Post.create/2 it calls the :create action
define :create, action: :create
# defining function Post.read_all/2 it calls the :read action
define :read_all, action: :read
# defining function Post.update/2 it calls the :update action
define :update, action: :update
# defining function Post.destroy/2 it calls the :destroy action
define :destroy, action: :destroy
# defining function Post.get_by_id/2
# it calls the :by_id action with the argument :id
define :get_by_id, args: [:id], action: :by_id
end
```
> Note: The function name doesn't have to match the action name in any way. You could also write:
updated_post = MyAshPhoenixApp.Blog.Post.update!(new_post, %{content: "hello to you too!"})
# delete post
MyAshPhoenixApp.Blog.Post.destroy!(updated_post)
```
Now isn't that more convenient?
> Note: All functions that interact with an Ash resource have a safe and unsafe version. For example there are two create functions `create/2` and `create!/2`. `create/2` returns `{:ok, resource}` or `{:error, reason}`. `create!/2` will return just the resource on success and will raise an error on failure.
Now we know how to interact with our resource, let's connect it to a simple Phoenix LiveView. Here is the LiveView below. If you are using phoenix live_view <= 0.18, you will need to use `let={}` instead of `:let={}`.
All being well you should be able to load up what we have just created on http://localhost:4000/posts.
You can see how using functions created by our `code_interface` makes it easy to integrate Ash with Phoenix.
You may also notice this is the first time we've used the AshPhoenix library. The AshPhoenix library contains utilities to help Ash integrate with Phoenix and LiveView Seamlessly. One of these utilities is `AshPhoenix.Form` which can automatically produce changesets to be used in the forms.
That's it for this guide. We've gone from 0 to a fully working Phoenix App using Ash. To get a closer look, see the accompanying repo [here](https://github.com/team-alembic/my_ash_phoenix_project).
## Where to Next?
We are really just scratching the surface of what can be done in Ash. Look below for what to look at next.
### Continue Learning
There's a few places you can go to learn more about how to use ash:
See the power Ash can bring to your web app or API. [Get authentication working in minutes](https://hexdocs.pm/ash_authentication_phoenix/getting-started-with-ash-authentication-phoenix.html).
Check out the [AshJsonApi](https://hexdocs.pm/ash_json_api/getting-started-with-json-api.html) and [AshGraphql](https://hexdocs.pm/ash_graphql/getting-started-with-graphql.html) extensions to effortlessly build APIs around your resources.