rc@73: # method-override
rc@73: 
rc@73: [![NPM version](https://badge.fury.io/js/method-override.svg)](http://badge.fury.io/js/method-override)
rc@73: [![Build Status](https://travis-ci.org/expressjs/method-override.svg?branch=master)](https://travis-ci.org/expressjs/method-override)
rc@73: [![Coverage Status](https://img.shields.io/coveralls/expressjs/method-override.svg?branch=master)](https://coveralls.io/r/expressjs/method-override)
rc@73: 
rc@73: Lets you use HTTP verbs such as PUT or DELETE in places where the client doesn't support it.
rc@73: 
rc@73: ## Install
rc@73: 
rc@73: ```sh
rc@73: $ npm install method-override
rc@73: ```
rc@73: 
rc@73: ## API
rc@73: 
rc@73: **NOTE** It is very important that this module is used **before** any module that
rc@73: needs to know the method of the request (for example, it _must_ be used prior to
rc@73: the `csurf` module).
rc@73: 
rc@73: ### methodOverride(getter, options)
rc@73: 
rc@73: Create a new middleware function to override the `req.method` property with a new
rc@73: value. This value will be pulled from the provided `getter`.
rc@73: 
rc@73: - `getter` - The getter to use to look up the overridden request method for the request. (default: `X-HTTP-Method-Override`)
rc@73: - `options.methods` - The allowed methods the original request must be in to check for a method override value. (default: `['POST']`)
rc@73: 
rc@73: If the found method is supported by node.js core, then `req.method` will be set to
rc@73: this value, as if it has originally been that value. The previous `req.method`
rc@73: value will be stored in `req.originalMethod`.
rc@73: 
rc@73: #### getter
rc@73: 
rc@73: This is the method of getting the override value from the request. If a function is provided,
rc@73: the `req` is passed as the first argument, the `res as the second argument and the method is
rc@73: expected to be returned. If a string is provided, the string is used to look up the method
rc@73: with the following rules:
rc@73: 
rc@73: - If the string starts with `X-`, then it is treated as the name of a header and that header
rc@73:   is used for the method override. If the request contains the same header multiple times, the
rc@73:   first occurrence is used.
rc@73: - All other strings are treated as a key in the URL query string.
rc@73: 
rc@73: #### options.methods
rc@73: 
rc@73: This allows the specification of what methods(s) the request *MUST* be in in order to check for
rc@73: the method override value. This defaults to only `POST` methods, which is the only method the
rc@73: override should arrive in. More methods may be specified here, but it may introduce security
rc@73: issues and cause weird behavior when requests travel through caches. This value is an array
rc@73: of methods in upper-case. `null` can be specified to allow all methods.
rc@73: 
rc@73: ## Examples
rc@73: 
rc@73: ### override using a header
rc@73: 
rc@73: To use a header to override the method, specify the header name
rc@73: as a string argument to the `methodOverride` function. To then make
rc@73: the call, send  a `POST` request to a URL with the overridden method
rc@73: as the value of that header.
rc@73: 
rc@73: ```js
rc@73: var connect        = require('connect')
rc@73: var methodOverride = require('method-override')
rc@73: 
rc@73: // override with the X-HTTP-Method-Override header in the request
rc@73: app.use(methodOverride('X-HTTP-Method-Override'))
rc@73: ```
rc@73: 
rc@73: Example call with header override using `curl`:
rc@73: 
rc@73: ```
rc@73: curl -XPOST -H'X-HTTP-Method-Override: DELETE' --verbose http://localhost:3000/resource
rc@73: > POST /resource HTTP/1.1
rc@73: > Host: localhost:3000
rc@73: > X-HTTP-Method-Override: DELETE
rc@73: >
rc@73: Cannot DELETE /resource
rc@73: ```
rc@73: 
rc@73: ### override using a query value
rc@73: 
rc@73: To use a query string value to override the method, specify the query
rc@73: string key as a string argument to the `methodOverride` function. To
rc@73: then make the call, send  a `POST` request to a URL with the overridden
rc@73: method as the value of that query string key.
rc@73: 
rc@73: ```js
rc@73: var connect        = require('connect')
rc@73: var methodOverride = require('method-override')
rc@73: 
rc@73: // override with POST having ?_method=DELETE
rc@73: app.use(methodOverride('_method'))
rc@73: ```
rc@73: 
rc@73: Example call with query override using `curl`:
rc@73: 
rc@73: ```
rc@73: curl -XPOST --verbose http://localhost:3000/resource?_method=DELETE
rc@73: > POST /resource?_method=DELETE HTTP/1.1
rc@73: > Host: localhost:3000
rc@73: >
rc@73: Cannot DELETE /resource?_method=DELETE
rc@73: ```
rc@73: 
rc@73: ### multiple format support
rc@73: 
rc@73: ```js
rc@73: var connect        = require('connect')
rc@73: var methodOverride = require('method-override')
rc@73: 
rc@73: // override with different headers; last one takes precedence
rc@73: app.use(methodOverride('X-HTTP-Method'))          // Microsoft
rc@73: app.use(methodOverride('X-HTTP-Method-Override')) // Google/GData
rc@73: app.use(methodOverride('X-Method-Override'))      // IBM
rc@73: ```
rc@73: 
rc@73: ### custom logic
rc@73: 
rc@73: You can implement any kind of custom logic with a function for the `getter`. The following
rc@73: implements the logic for looking in `req.body` that was in `method-override` 1:
rc@73: 
rc@73: ```js
rc@73: var bodyParser     = require('body-parser')
rc@73: var connect        = require('connect')
rc@73: var methodOverride = require('method-override')
rc@73: 
rc@73: app.use(bodyParser.urlencoded())
rc@73: app.use(methodOverride(function(req, res){
rc@73:   if (req.body && typeof req.body === 'object' && '_method' in req.body) {
rc@73:     // look in urlencoded POST bodies and delete it
rc@73:     var method = req.body._method
rc@73:     delete req.body._method
rc@73:     return method
rc@73:   }
rc@73: }))
rc@73: ```
rc@73: 
rc@73: ## License
rc@73: 
rc@73: The MIT License (MIT)
rc@73: 
rc@73: Copyright (c) 2014 Jonathan Ong me@jongleberry.com
rc@73: 
rc@73: Permission is hereby granted, free of charge, to any person obtaining a copy
rc@73: of this software and associated documentation files (the "Software"), to deal
rc@73: in the Software without restriction, including without limitation the rights
rc@73: to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
rc@73: copies of the Software, and to permit persons to whom the Software is
rc@73: furnished to do so, subject to the following conditions:
rc@73: 
rc@73: The above copyright notice and this permission notice shall be included in
rc@73: all copies or substantial portions of the Software.
rc@73: 
rc@73: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
rc@73: IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
rc@73: FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
rc@73: AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
rc@73: LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
rc@73: OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
rc@73: THE SOFTWARE.