README

A simple extensible laravel collection macro that evaluates the position or ranking of items in a collection and appends the position to each item with a key of your choice. The default key is 'position'

Installation

You can install the package via composer:

composer require codewithkyrian/laravel_position

You can publish the config file with:

php artisan vendor:publish --tag="position-config"

This is the contents of the published config file:

return [
    /**
     * The default key to use when adding the position to each item
     * in the collection. It could still be overridden when calling
     * method by passing a string as the second argument.
     */
    'key' => 'position',

    /**
     * Whether to show the total number of items in the collection
     * in the position text eg. 12th out of 30
     */
    'show_total' => false,

    /**
     * The text to join the position and the total number of items
     * in the collection
     */
    'join_text' => 'out of'
];

And you're done. You can now use the macro anywhere in your project.

Usage

To use the macro, you have to call the method rankBy on the collection instance while passing the key to be used for the ranking as the first arguement. This package can be used on a collection whether the items in it are arrays or objects.

$items = collect(
    [
        [ 'name' => 'Mr A', 'score' => 100 ],
        [ 'name' => 'Mr B', 'score' => 74 ],
        [ 'name' => 'Mr C', 'score' => 60 ],
        [ 'name' => 'Mr D', 'score' => 83 ],
        [ 'name' => 'Mr E', 'score' => 89 ],
    ]
);
$rankedItems = $items->rankBy('score');
dd($rankedItems->toArray());

/*
array:5 [▼
  0 => array:3 [▼
    "name" => "Mr A"
    "score" => 100
    "position" => "1st"
  ]
  1 => array:3 [▼
    "name" => "Mr E"
    "score" => 89
    "position" => "3rd"
  ]
  2 => array:3 [▼
    "name" => "Mr D"
    "score" => 83
    "position" => "4th"
  ]
  3 => array:3 [▼
    "name" => "Mr B"
    "score" => 74
    "position" => "5th"
  ]
  4 => array:3 [▼
    "name" => "Mr C"
    "score" => 60
    "position" => "6th"
  ]
]
*/

You can also pass a composite key in the dot notation form for collection with nested values.

$users = collect(
    [
        [ 
            'name' => 'Mr A', 
            'result' => [
                'score' => 100, 'status' => 1
            ]
        ],
        [ 
            'name' => 'Mr B', 
            'result' => [
                'score' => 74, 'status' => 1
            ]
        ],
        [ 
            'name' => 'Mr C', 
            'result' => [
                'score' => 60, 'status' => 1
            ]
        ],
        [ 
            'name' => 'Mr D', 
            'result' => [
                'score' => 83, 'status' => 1
            ]
        ]
    ]
);
$rankedUsers = $users->rankBy('result.score');
echo ($rankedUsers->toArray());

/*
array:4 [▼
  0 => array:3 [▼
    "name" => "Mr A"
    "result" => array:2 [▼
      "score" => 100
      "status" => 1
    ]
    "position" => "1st"
  ]
  1 => array:3 [▼
    "name" => "Mr D"
    "result" => array:2 [▼
      "score" => 83
      "status" => 1
    ]
    "position" => "3rd"
  ]
  2 => array:3 [▼
    "name" => "Mr B"
    "result" => array:2 [▼
      "score" => 74
      "status" => 1
    ]
    "position" => "4th"
  ]
  3 => array:3 [▼
    "name" => "Mr C"
    "result" => array:2 [▼
      "score" => 60
      "status" => 1
    ]
    "position" => "5th"
  ]
]
*/

To further customize the behaviour of the macro, you could pass a second argument to control the key used to output the position on the items. By default, it is position. Remember, you can also change this from the key key in the package's config file.

$rankedItems = $items->rankBy('score', 'class_position');
echo ($rankedItems->toArray());

/*
array:5 [▼
  0 => array:3 [▼
    "name" => "Mr A"
    "score" => 100
    "class_position" => "1st"
  ]
  1 => array:3 [▼
    "name" => "Mr E"
    "score" => 89
    "class_position" => "3rd"
  ]
  2 => array:3 [▼
    "name" => "Mr D"
    "score" => 83
    "class_position" => "4th"
  ]
  3 => array:3 [▼
    "name" => "Mr B"
    "score" => 74
    "class_position" => "5th"
  ]
  4 => array:3 [▼
    "name" => "Mr C"
    "score" => 60
    "class_position" => "6th"
  ]
]
*/

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Kyrian Obikwelu
• All Contributors

License

The MIT License (MIT). Please see License File for more information.