Writing Queries
===============

Laravel-Parse's query builder provides a convenient, fluent interface to 
creating and running Parse queries. It can be used to perform most operations
in your application and has been optimized to use with Parse.

Retrieving All Rows From A Class
--------------------------------

You may use the Parse class name on construction to begin a query. The Query 
Builder returns a fluent query builder instance for the given class, allowing 
you to chain more constraints onto the query and then finally get the results 
using the `get` method:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   return (new Query('_User', 'App\User', true))->get();

May you have noticed the three arguments assigned due construction. 
The **first argument** represent the Parse class name to query. The 
**second argument** represent the full path of the corresponding Model. 
The **third argument** determine if you would like to use the master key 
by default (`true`) or not (`false`).

The `get` method returns an `Illuminate\\Support\\Collection` containing the 
results where each result is an instance of the PHP `StdClass` object. You may 
access each column's value by accessing the column as a property of the object:

.. code-block:: php

   foreach ($results as $result) {
       echo $result->name;
   }

Retrieving A Single Row / Column From A Class
---------------------------------------------

If you just need to retrieve a single row from the Parse class, you may use the 
`first` method. This method will return a single `StdClass` object:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = new Query('_User', 'App\User', true);
   $query = $query->where('name', 'Petra Musterfrau')->first();
   
   return $query->name;

First or New
^^^^^^^^^^^^

If you would like that a row you are looking for will be generated for you 
if it does not exist, you can use the `firstOrNew` method:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = new Query('Test', 'App\Test', false);

   $query = $query->where('string', 'This is petra\'s string.')->firstOrNew([
      'string' => "Petra's string"
   ]);
   
   return $query->string;

.. warning::
   New up an object does not meant that it will be saved in the database. You 
   have to save the new model manually using the `save` method in order to store
   it in Parse.

First or Create
^^^^^^^^^^^^^^^

If you would like that a row you are looking for will be generated and saved 
for you, you can use the `firstOrCreate` method:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = new Query('Test', 'App\Test', false);

   $query = $query->where('string', 'This is petra\'s string.')->firstOrCreate([
      'string' => "Petra's string"
   ]);
   
   return $query->string;

First Or Fail
^^^^^^^^^^^^^^^

If you would like that a `NotFoundHttpException` exception will be thrown if the 
searched entry does not exist, than you might use the `firstOrFail` method:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = new Query('Test', 'App\Test', false);

   $query = $query->where('string', 'This is petra\'s string.')->firstOrFail();
   
   return $query->string;

Find Object Model
-----------------

Use the `find` method in order to search an object model by its Parse `objectId`:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = new Query('Test', 'App\Test', false)->find('nzKMYFAWLE');

This will return the object if it can be found otherwise it throws an error 
exception that somebody is trying to get property of non-object.

Find Or New
^^^^^^^^^^^

If you would like that a row you are looking for will be generated for you 
if it does not exist, you can use the `findOrNew` method:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = (new Query('Test', 'App\Test', true))->findOrNew('nzKMYFAWZE');

   return $query;

.. warning::
   New up an object does not meant that it will be saved in the database. You 
   have to save the new model manually using the `save` method in order to store
   it in Parse.

First Or Fail
^^^^^^^^^^^^^^^

If you would like that a `NotFoundHttpException` exception will be thrown if the 
searched entry does not exist, than you might use the `firstOrFail` method:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = new Query('Test', 'App\Test', false);

   $query = $query->findOrFail('nzKMYFAWZE');
   
   return $query->string;

Count Results
-------------

You can use the `count` method in order to count the results:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   $query = (new Query('_User', 'App\User', true))->get();

   return $query->count();

Where Clauses
-------------

Simple Where Clauses
^^^^^^^^^^^^^^^^^^^^

You may use the `where` method on a query builder instance to add `where` clauses 
to the query. The most basic call to `where` requires three arguments. The 
**first argument** is the name of the column. The **second argument** is an 
operator, which can be any of the parse's supported operators. Finally, the 
**third argument** is the value to evaluate against the column.

For example, here is a query that verifies the value of the "votes" column is equal to 100:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   return (new Query('_User', 'App\User', true))->where('votes', '=', 100)->get();
   
Where Operators
^^^^^^^^^^^^^^^

========  ===========
Operator  Translation
========  ===========
\=        equalTo
!=        notEqualTo
>         greaterThan
>=        greaterThanOrEqualTo
<         lessThan
<=        lessThanOrEqualTo
in        containedIn
========  ===========

Ordering
--------

The `orderBy` method allows you to sort the result of the query by a given column. 
The **first argument** to the `orderBy` method should be the column you wish to 
sort by, while the **second argument** controls the direction of the sort and may 
be either `asc` or `desc`:

.. code-block:: php

   use Sirthxalot\Parse\Query;

   return (new Query('_User', 'App\User', true))->orderBy('name', 'desc')->get();