{"id":13747421,"url":"https://github.com/heartcombo/has_scope","last_synced_at":"2025-05-09T08:32:40.049Z","repository":{"id":743900,"uuid":"395276","full_name":"heartcombo/has_scope","owner":"heartcombo","description":"Map incoming controller parameters to named scopes in your resources","archived":false,"fork":false,"pushed_at":"2024-04-09T19:59:21.000Z","size":174,"stargazers_count":1667,"open_issues_count":3,"forks_count":89,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-05-02T07:01:50.838Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://blog.plataformatec.com.br/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heartcombo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2009-12-04T11:45:59.000Z","updated_at":"2025-04-15T14:54:05.000Z","dependencies_parsed_at":"2023-01-13T10:39:08.072Z","dependency_job_id":"e5283cce-b566-4b5c-97fc-aecd3f9f5d8a","html_url":"https://github.com/heartcombo/has_scope","commit_stats":{"total_commits":188,"total_committers":39,"mean_commits":4.82051282051282,"dds":0.5851063829787234,"last_synced_commit":"7cb25ad9b9e2ed343a4f17adb1f8158c9792be1d"},"previous_names":["plataformatec/has_scope"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heartcombo%2Fhas_scope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heartcombo%2Fhas_scope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heartcombo%2Fhas_scope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heartcombo%2Fhas_scope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heartcombo","download_url":"https://codeload.github.com/heartcombo/has_scope/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252305224,"owners_count":21726621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T06:01:28.320Z","updated_at":"2025-05-09T08:32:39.989Z","avatar_url":"https://github.com/heartcombo.png","language":"Ruby","readme":"## HasScope\n\n[![Gem Version](https://fury-badge.herokuapp.com/rb/has_scope.svg)](http://badge.fury.io/rb/has_scope)\n\n_HasScope_ allows you to dynamically apply named scopes to your resources based on an incoming set of parameters.\n\nThe most common usage is to map incoming controller parameters to named scopes for filtering resources, but it can be used anywhere.\n\n## Installation\n\nAdd `has_scope` to your bundle\n\n```ruby\nbundle add has_scope\n```\n\nor add it manually to your Gemfile if you prefer.\n\n```ruby\ngem 'has_scope'\n```\n\n## Examples\n\nFor the following examples we'll use a model called graduations:\n\n```ruby\nclass Graduation \u003c ActiveRecord::Base\n  scope :featured, -\u003e { where(featured: true) }\n  scope :by_degree, -\u003e degree { where(degree: degree) }\n  scope :by_period, -\u003e started_at, ended_at { where(\"started_at = ? AND ended_at = ?\", started_at, ended_at) }\nend\n```\n\n### Usage 1: Rails Controllers\n\n_HasScope_ exposes the `has_scope` method automatically in all your controllers. This is used to declare the scopes a controller action can use to filter a resource:\n\n```ruby\nclass GraduationsController \u003c ApplicationController\n  has_scope :featured, type: :boolean\n  has_scope :by_degree\n  has_scope :by_period, using: %i[started_at ended_at], type: :hash\nend\n```\n\nTo apply the scopes to a specific resource, you just need to call `apply_scopes`:\n\n```ruby\nclass GraduationsController \u003c ApplicationController\n  has_scope :featured, type: :boolean\n  has_scope :by_degree\n  has_scope :by_period, using: %i[started_at ended_at], type: :hash\n\n  def index\n    @graduations = apply_scopes(Graduation).all\n  end\nend\n```\n\nThen for each request to the `index` action, _HasScope_ will automatically apply the scopes as follows:\n\n``` ruby\n# GET /graduations\n# No scopes applied\n#=\u003e brings all graduations\napply_scopes(Graduation).all == Graduation.all\n\n# GET /graduations?featured=true\n# The \"featured' scope is applied\n#=\u003e brings featured graduations\napply_scopes(Graduation).all == Graduation.featured\n\n# GET /graduations?by_period[started_at]=20100701\u0026by_period[ended_at]=20101013\n#=\u003e brings graduations in the given period\napply_scopes(Graduation).all == Graduation.by_period('20100701', '20101013')\n\n# GET /graduations?featured=true\u0026by_degree=phd\n#=\u003e brings featured graduations with phd degree\napply_scopes(Graduation).all == Graduation.featured.by_degree('phd')\n\n# GET /graduations?finished=true\u0026by_degree=phd\n#=\u003e brings only graduations with phd degree because we didn't declare finished in our controller as a permitted scope\napply_scopes(Graduation).all == Graduation.by_degree('phd')\n```\n\n#### Check for currently applied scopes\n\n_HasScope_ creates a helper method called `current_scopes` to retrieve all the scopes applied. As it's a helper method, you'll be able to access it in the controller action or the view rendered in that action.\n\nComing back to one of the examples above:\n\n```ruby\n# GET /graduations?featured=true\u0026by_degree=phd\n#=\u003e brings featured graduations with phd degree\napply_scopes(Graduation).all == Graduation.featured.by_degree('phd')\n```\n\nCalling `current_scopes` after `apply_scopes` in the controller action or view would return the following:\n\n```\ncurrent_scopes\n#=\u003e { featured: true, by_degree: 'phd' }\n```\n\n### Usage 2: Standalone Mode\n\n_HasScope_ can also be used in plain old Ruby objects (PORO). To implement the previous example using this approach, create a bare object and include `HasScope` to get access to its features:\n\n\u003e Note: We'll create a simple version of a query object for this example as this type of object can have multiple different implementations.\n\n\n```ruby\nclass GraduationsSearchQuery\n  include HasScope\n  # ...\nend\n```\n\nNext, declare the scopes to be used the same way:\n\n```ruby\nclass GraduationsSearchQuery\n  include HasScope\n\n  has_scope :featured, type: :boolean\n  has_scope :by_degree\n  has_scope :by_period, using: %i[started_at ended_at], type: :hash\n  # ...\nend\n```\n\nNow, allow your object to perform the query by exposing a method that will use `apply_scopes`:\n\n```ruby\nclass GraduationsSearchQuery\n  include HasScope\n\n  has_scope :featured, type: :boolean\n  has_scope :by_degree\n  has_scope :by_period, using: %i[started_at ended_at], type: :hash\n\n  def perform(collection: Graduation, params: {})\n    apply_scopes(collection, params)\n  end\nend\n```\n\nNote that `apply_scopes` receives a `Hash` as a second argument, which represents the incoming params that determine which scopes should be applied to the model/collection. It defaults to `params` for compatibility with controllers, which is why it's not necessary to pass that second argument in the controller context.\n\nNow in your controller you can call the `GraduationsSearchQuery` with the incoming parameters from the controller:\n\n```ruby\nclass GraduationsController \u003c ApplicationController\n  def index\n    graduations_query = GraduationsSearchQuery.new\n    @graduations = graduations_query.perform(collection: Graduation, params: params)\n  end\nend\n```\n\n#### Accessing `current_scopes`\n\nIn the controller context, `current_scopes` is made available as a helper method to the controller and view, but it's a `protected` method of _HasScope_'s implementation, to prevent it from becoming publicly accessible outside of _HasScope_ itself. This means that the object implementation showed above has access to `current_scopes` internally, but it's not exposed to other objects that interact with it.\n\nIf you need to access `current_scopes` elsewhere, you can change the method visibility like so:\n\n```ruby\nclass GraduationsSearchQuery\n  include HasScope\n\n  # ...\n\n  public :current_scopes\n\n  # ...\nend\n```\n\n## Options\n\n`has_scope` supports several options:\n\n* `:type` - Checks the type of the parameter sent.\n  By default, it does not allow hashes or arrays to be given,\n  except if type `:hash` or `:array` are set.\n  Symbols are never permitted to prevent memory leaks, so ensure any routing\n  constraints you have that add parameters use string values.\n\n* `:only` - In which actions the scope is applied.\n\n* `:except` - In which actions the scope is not applied.\n\n* `:as` - The key in the params hash expected to find the scope. Defaults to the scope name.\n\n* `:using` - The subkeys to be used as args when type is a hash.\n\n* `:in` - A shortcut for combining the `:using` option with nested hashes.\n\n* `:if` - Specifies a method or proc to call to determine if the scope should apply. Passing a string is deprecated and it will be removed in a future version.\n\n* `:unless` - Specifies a method or proc to call to determine if the scope should NOT apply. Passing a string is deprecated and it will be removed in a future version.\n\n* `:default` - Default value for the scope. Whenever supplied the scope is always called.\n\n* `:allow_blank` - Blank values are not sent to scopes by default. Set to true to overwrite.\n\n## Boolean usage\n\nIf `type: :boolean` is set it just calls the named scope, without any arguments, when parameter\nis set to a \"true\" value. `'true'` and `'1'` are parsed as `true`, everything else as `false`.\n\nWhen boolean scope is set up with `allow_blank: true`, it will call the scope with the value as\nany usual scope.\n\n```ruby\nhas_scope :visible, type: :boolean\nhas_scope :active, type: :boolean, allow_blank: true\n\n# and models with\nscope :visible, -\u003e { where(visible: true) }\nscope :active, -\u003e(value = true) { where(active: value) }\n```\n\n_Note_: it is not possible to apply a boolean scope with just the query param being present, e.g.\n`?active`, that's not considered a \"true\" value (the param value will be `nil`), and thus the\nscope will be called with `false` as argument. In order for the scope to receive a `true` argument\nthe param value must be set to one of the \"true\" values above, e.g. `?active=true` or `?active=1`.\n\n## Block usage\n\n`has_scope` also accepts a block in case we need to manipulate the given value and/or call the scope in some custom way. Usually three arguments are passed to the block:\n- The instance of the controller or object where it's included\n- The current scope chain\n- The value of the scope to apply\n\n\u003e 💡 We suggest you name the first argument depending on how you're using _HasScope_. If it's the controller, use the word \"controller\". If it's a query object for example, use \"query\", or something meaningful for that context (or simply use \"context\"). In the following examples, we'll use controller for simplicity.\n\n```ruby\nhas_scope :category do |controller, scope, value|\n  value != 'all' ? scope.by_category(value) : scope\nend\n```\n\nWhen used with booleans without `:allow_blank`, it just receives two arguments\nand is just invoked if true is given:\n\n```ruby\nhas_scope :not_voted_by_me, type: :boolean do |controller, scope|\n  scope.not_voted_by(controller.current_user.id)\nend\n```\n\n## Keyword arguments\n\nScopes with keyword arguments need to be called in a block:\n\n```ruby\n# in the model\nscope :for_course, lambda { |course_id:| where(course_id: course_id) }\n\n# in the controller\nhas_scope :for_course do |controller, scope, value|\n  scope.for_course(course_id: value)\nend\n```\n\n## Apply scope on every request\n\nTo apply scope on every request set default value and `allow_blank: true`:\n\n```ruby\nhas_scope :available, default: nil, allow_blank: true, only: :show, unless: :admin?\n\n# model:\nscope :available, -\u003e(*) { where(blocked: false) }\n```\n\nThis will allow usual users to get only available items, but admins will\nbe able to access blocked items too.\n\n## Check which scopes have been applied\n\nTo check which scopes have been applied, you can call `current_scopes` from the controller or view.\nThis returns a hash with the scope name as the key and the scope value as the value.\n\nFor example, if a boolean `:active` scope has been applied, `current_scopes` will return `{ active: true }`.\n\n## Supported Ruby / Rails versions\n\nWe intend to maintain support for all Ruby / Rails versions that haven't reached end-of-life.\n\nFor more information about specific versions please check [Ruby](https://www.ruby-lang.org/en/downloads/branches/)\nand [Rails](https://guides.rubyonrails.org/maintenance_policy.html) maintenance policies, and our test matrix.\n\n## Bugs and Feedback\n\nIf you discover any bugs or want to drop a line, feel free to create an issue on GitHub.\n\n## License\n\nMIT License. Copyright 2020-2024 Rafael França, Carlos Antônio da Silva. Copyright 2009-2019 Plataformatec.\n","funding_links":[],"categories":["Ruby","Search"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheartcombo%2Fhas_scope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheartcombo%2Fhas_scope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheartcombo%2Fhas_scope/lists"}