Packages
ecto
0.5.1
3.14.1
3.14.0
3.13.6
3.13.5
3.13.4
3.13.3
3.13.2
3.13.1
3.13.0
3.12.6
3.12.5
3.12.4
3.12.3
3.12.2
3.12.1
3.12.0
3.11.2
3.11.1
3.11.0
3.10.3
3.10.2
3.10.1
3.10.0
3.9.6
3.9.5
3.9.4
3.9.3
3.9.2
3.9.1
3.9.0
3.8.4
3.8.3
3.8.2
3.8.1
3.8.0
3.7.2
3.7.1
3.7.0
3.6.2
3.6.1
3.6.0
3.5.8
3.5.7
3.5.6
3.5.5
3.5.4
3.5.3
3.5.2
3.5.1
3.5.0
3.5.0-rc.1
3.5.0-rc.0
3.4.6
3.4.5
3.4.4
3.4.3
3.4.2
3.4.1
3.4.0
3.3.4
3.3.3
3.3.2
3.3.1
3.3.0
3.2.5
3.2.4
3.2.3
3.2.2
3.2.1
3.2.0
3.1.7
3.1.6
3.1.5
3.1.4
3.1.3
3.1.2
3.1.1
3.1.0
3.0.9
3.0.8
3.0.7
3.0.6
3.0.5
3.0.4
3.0.3
3.0.2
3.0.1
3.0.0
3.0.0-rc.1
3.0.0-rc.0
2.2.12
2.2.11
2.2.10
2.2.9
2.2.8
2.2.7
2.2.6
2.2.5
2.2.4
2.2.3
2.2.2
2.2.1
2.2.0
2.2.0-rc.1
2.2.0-rc.0
2.1.6
2.1.5
2.1.4
2.1.3
2.1.2
2.1.1
2.1.0
2.1.0-rc.5
2.1.0-rc.4
2.1.0-rc.3
2.1.0-rc.2
2.1.0-rc.1
2.1.0-rc.0
2.0.6
2.0.5
2.0.4
2.0.3
2.0.2
2.0.1
2.0.0
2.0.0-rc.6
2.0.0-rc.5
2.0.0-rc.4
2.0.0-rc.3
2.0.0-rc.2
2.0.0-rc.1
2.0.0-rc.0
2.0.0-beta.2
2.0.0-beta.1
2.0.0-beta.0
1.1.9
1.1.8
1.1.7
1.1.6
1.1.5
1.1.4
1.1.3
1.1.2
1.1.1
1.1.0
1.0.7
1.0.6
1.0.5
1.0.4
1.0.3
1.0.2
1.0.1
1.0.0
0.16.0
0.15.0
0.14.3
0.14.2
0.14.1
0.14.0
0.13.1
0.13.0
0.12.1
0.12.0
0.12.0-rc
0.11.3
0.11.2
0.11.1
0.11.0
0.10.3
0.10.2
0.10.1
0.10.0
0.9.0
0.8.1
0.8.0
0.7.2
0.7.1
0.7.0
0.6.0
0.5.1
0.5.0
0.4.0
0.3.0
0.2.8
0.2.7
0.2.6
0.2.5
0.2.4
0.2.3
0.2.2
0.2.1
0.2.0
0.1.0
A toolkit for data mapping and language integrated query for Elixir
Current section
Files
Jump to
Current section
Files
lib/ecto/model/callbacks.ex
defmodule Ecto.Model.Callbacks do
@moduledoc """
Define module-level callbacks in models.
A callback is invoked by your `Ecto.Repo` before (or after)
particular events. Callbacks receive changesets, must
always return a changeset back and always run inside a transaction.
Callbacks in Ecto are useful for data consistency, like keeping
counters, setting field values and so on. For this reason, callbacks
cannot abort and are invoked after the data is validated.
Therefore, don't use callbacks for validation, enforcing business
rules or performing actions unrelated to the data itself, like
sending e-mails.
Finally keep in mind callbacks are not invoked on bulk actions
such as `Ecto.Repo.update_all/3` or `Ecto.Repo.delete_all/2`.
## Example
defmodule User do
use Ecto.Model.Callbacks
after_insert Stats, :increase_user_count
def increase_user_count(changeset)
# ...
end
end
When creating the user, the `after_insert` callbacks will be
invoked with a changeset as argument. Multiple callbacks
can be defined, they will be invoked in order of declaration.
A callback can be defined in the following formats:
# Invoke the local function increase_user_count
after_insert :increase_user_count
# Invoke the local function increase_user_count
# with the given arguments (changeset is prepended)
after_insert :increase_user_count, ["foo", "bar"]
# Invoke the remote function increase_user_count
after_insert Stats, :increase_user_count
# Invoke the remote function increase_user_count
# with the given arguments (changeset is prepended)
after_insert Stats, :increase_user_count, ["foo", "bar"]
"""
@doc false
defmacro __using__(_opts) do
quote do
import Ecto.Model.Callbacks
@before_compile Ecto.Model.Callbacks
@ecto_callbacks %{}
end
end
@doc false
defmacro __before_compile__(env) do
callbacks = Module.get_attribute env.module, :ecto_callbacks
for {event, callbacks} <- callbacks do
body = Enum.reduce Enum.reverse(callbacks),
quote(do: changeset), &compile_callback/2
quote do
def unquote(event)(changeset), do: unquote(body)
end
end
end
# Callback macros
@doc """
Adds a callback that is invoked before the model is inserted
into the repository.
Since on insert all the model fields plus changeset changes
are sent to the repository, the callback will receive an
`Ecto.Changeset` with all the model fields and changes in
the `changeset.changes` field. At this point, the changeset
was already validated and is always valid.
The callback must return a changeset.
## Example
before_insert User, :generate_permalink
"""
defmacro before_insert(function, args \\ []),
do: register_callback(:before_insert, function, args, [])
@doc """
Same as `before_insert/2` but with arguments.
"""
defmacro before_insert(module, function, args),
do: register_callback(:before_insert, module, function, args)
@doc """
Adds a callback that is invoked after the model is inserted
into the repository.
The callback receives an `Ecto.Changeset` with both repository
values and changeset changes already applied to the model.
The callback must return a changeset.
## Example
after_insert Stats, :increase_user_count
"""
defmacro after_insert(function, args \\ []),
do: register_callback(:after_insert, function, args, [])
@doc """
Same as `after_insert/2` but with arguments.
"""
defmacro after_insert(module, function, args),
do: register_callback(:after_insert, module, function, args)
@doc """
Adds a callback that is invoked before the model is updated.
The callback receives an `Ecto.Changeset` with the changes
to be sent to the database in the `changeset.changes` field.
At this point, the changeset was already validated and is
always valid.
The callback must return a changeset.
## Example
before_update User, :set_update_at_timestamp
"""
defmacro before_update(function, args \\ []),
do: register_callback(:before_update, function, args, [])
@doc """
Same as `before_update/2` but with arguments.
"""
defmacro before_update(module, function, args),
do: register_callback(:before_update, module, function, args)
@doc """
Adds a callback that is invoked after the model is updated.
The callback receives an `Ecto.Changeset` with both repository
values and changeset changes already applied to the model.
The callback must return a changeset.
## Example
after_update User, :notify_account_change
"""
defmacro after_update(function, args \\ []),
do: register_callback(:after_update, function, args, [])
@doc """
Same as `after_update/2` but with arguments.
"""
defmacro after_update(module, function, args),
do: register_callback(:after_update, module, function, args)
@doc """
Adds a callback that is invoked before the model is deleted
from the repository.
The callback receives an `Ecto.Changeset`. At this point, the
changeset was already validated and is always valid.
The callback must return a changeset.
## Example
before_delete User, :copy_to_archive
"""
defmacro before_delete(function, args \\ []),
do: register_callback(:before_delete, function, args, [])
@doc """
Same as `before_delete/2` but with arguments.
"""
defmacro before_delete(module, function, args),
do: register_callback(:before_delete, module, function, args)
@doc """
Adds a callback that is invoked before the model is deleted
from the repository.
The callback receives an `Ecto.Changeset` with the model
stored in it. The callback must return a changeset.
## Example
after_delete User, :notify_garbage_collectors
"""
defmacro after_delete(function, args \\ []),
do: register_callback(:after_delete, function, args, [])
@doc """
Same as `after_delete/2` but with arguments.
"""
defmacro after_delete(module, function, args),
do: register_callback(:after_delete, module, function, args)
defp register_callback(event, module, function, args) do
quote bind_quoted: binding() do
callback = {module, function, args}
@ecto_callbacks Map.update(@ecto_callbacks, event, [callback], &[callback|&1])
end
end
defp compile_callback({function, args, []}, acc)
when is_atom(function) and is_list(args) do
error = callback_error("#{function}/#{length(args)+1}")
quote do
case unquote(function)(unquote(acc), unquote_splicing(args)) do
%Ecto.Changeset{} = changeset -> changeset
other -> raise unquote(error) <> inspect(other)
end
end
end
defp compile_callback({module, function, args}, acc)
when is_atom(module) and is_atom(function) and is_list(args) do
error = callback_error("#{inspect module}.#{function}/#{length(args)+1}")
quote do
case unquote(module).unquote(function)(unquote(acc), unquote_splicing(args)) do
%Ecto.Changeset{} = changeset -> changeset
other -> raise unquote(error) <> inspect(other)
end
end
end
defp callback_error(callback) do
"expected callback #{callback} to return an Ecto.Changeset, got: "
end
@doc """
Applies stored callbacks in model to given data.
Checks wether the callback is defined on the model,
returns the data unchanged if it isn't.
This function expects a changeset as input.
## Examples
iex> changeset = Ecto.Changeset.cast(params, %User{}, ~w(name), ~w())
iex> Ecto.Model.Callbacks.__apply__ User, :before_delete, changeset
%Ecto.Changeset{...}
"""
def __apply__(module, callback, %Ecto.Changeset{} = changeset) do
if function_exported?(module, callback, 1) do
apply(module, callback, [changeset])
else
changeset
end
end
end