Damien MATHIEU

Je me souviens de mon cœur faisant des bonds lorsque le plugin has_finder de Nick Kallen a été implémenté dans rails core sous le nom de named_scope.
named_scope a rapidement rejoint la liste de mes outils préférés de par sa merveilleuse manière de créer des requêtes logiques encapsulées et réutilisables.
Alors qu’il avait ses points faibles (pour ne pas le nommer, le manque du support de :joins et :include), il a redéfini ma manière de penser la logique de mes modèles.
Une fois que vous avez gouté au plaisir des named_scopes, vous ne pouvez jamais revenir en arrière.

Et maintenant Rails 3 arrive avec son refactoring complet de ActiveRecord. Que deviennent nos cher named_scope ? Pour faire simple, cela a été renommé en scope et vous pouvez les utiliser comme vous le faisiez déjà … Mais de manière plus aisée.
Voyons un peu ce que l’on peut faire avec ces scopes dans Rails 3.

Usage basique

Supposons un modèle Post avec des champs published_at, title et content.
Dans rails 2.x, nous devrions définir les scopes published et recent.

class Post < ActiveRecord::Base
    named_scope :published, lambda {
        { :conditions =>
            ["posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now]
        }
    }
    named_scope :recent, : order => "posts.published_at DESC"
end

Avec Rails 3, l’architecture d’ActiveRecord est maintenant basée sur une classe Relation. Classe que vous pouvez voir comme une sorte de « named_scope on steroids », permettant de de chainer chaque requête directement dans ActiveRecord.

Vous pouvez voir comment utiliser les méthodes where, ordre etc dans l’article de Pratik sur cette nouvelle interface ou bien encore dans ce Railscast.
Comprendre ceci est important étant donné que les nouvelles scopes sont construites autour de cela.

Voyons comment. Voici nos deux différentes scopes portées sous Rails 3.

class Post < ActiveRecord::Base
    scope :published, lambda {
        where("posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now)
    }
    scope :recent, order("posts.published_at DESC")
end

Alors que la logique reste la même (les portions SQL), vous pouvez commencer à voir comment les scopes utilisent la nouvelle interface de requêtage pour construire directement la requête au lieu de construire un hash d’options comme c’était fait dans Rails 2.
Ceci est le tout premier aperçu de la flexibilité que la nouvelle interface apporte à nos scopes.
Elles ne sont plus construites différemment que n’importe quelle requête. Elles sont construites au dessus des mêmes méthodes que vous pouvez utiliser lorsque vous construisez directement vos requêtes.
Cette consistance est maintenant présent partout dans ActiveRecord.

Mais ce n’est pas tout …

Réutilisation des scopes

Supposons que nous désirions modifier notre scope « recent » pour n’inclure que les posts publiés. Nous avons déjà défini ce que published signifie et nous ne devrions donc pas avoir à le redéfinir pour créer une nouvelle scope.
Aucun problème ! Nous pouvons chainer les scopes elles mêmes et c’est ce que nous allons faire ici.

class Post < ActiveRecord::Base
    scope :published, lambda {
        where("posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now)
    }
    scope :published_since, lambda { |ago|
        published.where("posts.published_at >= ?", ago)
    }
    scope :recent, published.order("posts.published_at DESC")
end

Ca commence à devenir intéressant.

Construction dynamique

Déjà dans Rails 2.3, vous pouvez créer des scopes anonymes afin d’obtenir dynamiquement des scopes chainables selon vos besoins.
Un cas typique d’utilisation est lorsque vous désirez créer une méthode de recherche à laquelle vous pouvez toujours ajouter d’autres manipulations.

Par exemple pour chercher parmi nos posts, nous créons cette méthode qui retournera un scope que vous pourrez par la suite filtrer (notez l’utilisation de « scoped » pour démarrer la chaine avec une scope vide à laquelle d’autres peuvent être ajoutées).

class Post < ActiveRecord::Base
    class << self

        # Cherche dans les champs title et body la chaine donnée.
        # Démarre avec une scope vide et la construit pour chaque attribut.
        # Facilitera l'extraction des définitions des champs de recherche pour le futur.
        def search(q)
            [:title, :body].inject(scoped) do |combined_scope, attr|
                combined_scope.where("posts.#{attr} LIKE ?", "%#{q}%")
            end
        end
    end
end

L’utilisation de inject ici masque l’intérêt de cette méthode si vous n’avez pas l’habitude de voir de telles itérations. Voici une version plus aisée à comprendre contenant les champs de recherche en dur (et qui n’utilise même pas de scope anonyme).

class Post < ActiveRecord::Base
    class << self

        # Moins dynamique mais probablement plus lisible
        def search(q)
            query = "%#{q}%"
            where("posts.title LIKE ?", query).where("posts.body LIKE ?", query)
        end
    end
end

Vu que nous construisons nos scopes autour de la nouvelle interface qui est fortement chainable, nous pouvons faire la chose suivante avec notre méthode de recherche :

# What's in the db, titles ~= publish date
Post.all.collect(&:title) #=> ["1 week from now", "Now", "1 week ago", "2 weeks ago"]
Post.published.collect(&:title) #=> ["Now", "1 week ago", "2 weeks ago"]

# Combinaisons de recherche
Post.search('1').collect(&:title) #=> ["1 week from now", "1 week ago"]
Post.search('1').published.collect(&:title) #=> ["1 week ago"]
Post.search('w').published_since(10.days.ago).collect(&:title) #=> ["Now", "1 week ago"]
Post.search('w').order('created_at DESC').limit(2).collect(&:title) #=> ["2 weeks ago", "1 week ago"]

Vous pouvez imaginer un scénario ou des requêtes bien plus complexes pourront être construites en utilisant des scopes anonymes.
Cool non ?

Scopes multi modèles

Les scopes sont parfaites pour manipuler uniquement les colonnes d’un modèle unique. Mais elles peuvent également être utilisées pour construire des requêtes multi modèles (qui requièrent un join).
Ajoutons à nos posts des utilisateurs (qui peuvent être auteur ou commentateur) et écrivons quelques scopes sur le modèle User qui nous permettront de récupérer uniquement ceux ayant publié des billets et ceux qui ont commenté.

class User < ActiveRecord::Base
    has_many :posts, :foreign_key => :author_id
    has_many :comments

    # Récupération de tous les utilisateurs ayant publié un billet
    scope :published, lambda {
        joins("join posts on posts.author_id = users.id").
        where("posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now).
        group("users.id")
    }

    # Récupération de tous les utilisateurs qui ont commenté un billet
    scope :commented, joins("join comments on comments.user_id = users.id").group("users.id")
end

Notons également que ActiveRelation est également suffisamment intelligent pour savoir comment faire un join sur la définition de l’association, nous autorisant à placer cette relation en référence.

class User < ActiveRecord::Base
# Récupération de tous les utilisateurs ayant publié un billet
scope :published, lambda {
joins(:posts). # Inutile de rédiger le SQL
where("posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now).
group("users.id")
}

# Récupération de tous les utilisateurs qui ont commenté un billet
scope :commented, joins(:comments).group("users.id") # Just reference :comments
end

Vu que nous avons l’arsenal complet des opérateurs ActiveRecord à notre disposition dans les scopes, nous pouvons faire des join et des group by dans les scopes qui seront chainées dans les requêtes complexes. Chose que named_scope n’arrivait que rarement à faire.

# Récupération de tous les utilisateurs ayant publié un billet
User.published.collect(&:username) #=> ["tim", "dave"]
User.published.to_sql
  #=> SELECT "users".* FROM "users" join posts on posts.author_id = users.id
  #   WHERE (posts.published_at IS NOT NULL AND posts.published_at <= '2010-02-22 21:33:00.892308')
  #   GROUP BY users.id

# Récupération de tous les utilisateurs ayant posté un commentaire
User.commented.collect(&:username) #=> ["ryan", "john", "tim", "dave"]
User.commented.to_sql
  #=> SELECT "users".* FROM "users" join comments on comments.user_id = users.id
  #   GROUP BY users.id

# Combinaison pour récupérer tous les auteurs qui ont posté un commentaire
User.published.commented.collect(&:username) #=> ["tim", "dave"]
User.published.commented.to_sql
  #=> SELECT "users".* FROM "users"
  #   join posts on posts.author_id = users.id
  #   join comments on comments.user_id = users.id
  #   WHERE (posts.published_at IS NOT NULL AND posts.published_at <= '2010-02-22 21:33:00.892308')
  #   GROUP BY users.id

Opérations CRUD sur les scopes

Vu que ActiveRelation vous permet d’invoquer toutes les méthodes builder/update/destroy, celles-ci sont également accessibles pour les scopes.
Jouons un peu à faire des modifications sur nos scopes au lieu de se contenter de les récupérer.

# Incrémente le nombre de vues pour tous les billets publiés
Post.published.collect(&:views_count) #=> [59, 71, 42]
Post.published.update_all("views_count = views_count + 1")
Post.published.collect(&:views_count) #=> [60, 72, 43]

# On se moque des billets non publiés
Post.unpublished.size #=> 1
Post.unpublished.destroy_all
Post.unpublished.size #=> 0

Vous pouvez également créer un nouvel uplet avec des scopes existantes. Supposons que nous avons une scope (très peu utile) qui ne récupère que les posts avec un certain titre

class Post < ActiveRecord::Base
    scope :titled_luda, where(:title => 'Luda')
end

Nous pouvons utiliser cette scope pour créer de nouvelles instances (tout comme new, create, …)

Post.titled_luda.size #=> 0
Post.titled_luda.build
  #=> #<Post id: nil, title: "Luda", ...>

Pour les grands fou

Une chose qui m’a toujours choqué est la manière dont la logique pour ce qui fait qu’un billet est publié est séparée entre les scopes de la classe Post et celles de la classe User.
Afin de se rafraichir la mémoire

class Post < ActiveRecord::Base
    scope :published, lambda {
        where("posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now)
    }
end

Ainsi que

class User < ActiveRecord::Base

    scope :published, lambda {
        joins(:posts).
        where("posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now).
        group("users.id")
    }
end

Tout bon développeur va instantanément noter la duplication du where(« posts.published_at IS NOT NULL AND posts.published_at <= ?", Time.zone.now).

Heureusemnt il existe une méthode pour éviter cette répétition : un merge dont l’alias est ‘&’.
Voyons comment nous pouvons utiliser scope#& afin de faire référence à Post.published dans la scope User.published.

class User < ActiveRecord::Base

    scope :published, lambda {
        joins(:posts).group("users.id") & Post.published
    }
end

Et voici la requête SQL qui sera générée :

User.published.to_sql
  #=> SELECT users.* FROM "users"
  #   INNER JOIN "posts" ON "posts"."author_id" = "users"."id"
  #   WHERE (posts.published_at IS NOT NULL AND posts.published_at <= '2010-02-27 02:55:45.063181')
  #   GROUP BY users.id

Notez comment les conditions définies dans Post.published sont mergées dans les relations join et group de la scope User.published ?
Et ceci fonctionne avec toutes les relations mergables.

Conclusion

Ce billet dérive un petit peu dans une explication de la nouvelle interface de requêtage SQL avec ActiveRecord dans Rails 3 afin d’entrer dans les détails des scopes.
Cependant aucune des nouvelles fonctionnalités des scopes n’aurait pu être mise en place sans ces nouveautés d’ActiveRecord.
Donc si vous êtes encore un petit confus à propos de cela, n’hésitez pas à vous documenter encore un petit peu plus à propos de la nouvelle API ActiveRecord avant de vous penchez sur les scopes.
Une fois que vous aurez ces bases, vous ne pourrez plus vous passer des scopes !