add new phpdoc

guide/basics.rst

@@ -0,0 +1,105 @@
+======
+Basics
+======
+
+First step is to include the Composer autoload file and `import <https://www.php.net/manual/en/language.namespaces.importing.php>`_ any required classes.
+
+.. code:: php
+
+   <?php
+
+   use Discord\Discord;
+   use Discord\WebSockets\Intents;
+   use Discord\WebSockets\Event;
+
+   include __DIR__.'/vendor/autoload.php';
+
+The Discord instance can be set up with an array of options. All are optional except for token:
+
+.. code:: php
+
+   $discord = new Discord([
+       'token' => 'Your-Token-Here',
+       'intents' => [
+           Intents::GUILDS, Intents::GUILD_BANS, // ...
+       ],
+       // or
+       'intents' => 12345,
+       // or
+       'intents' => Intents::getDefaultIntents() | Intents::GUILD_MEMBERS, // default intents as well as guild members
+       'loadAllMembers' => false,
+       'storeMessages' => false,
+       'retrieveBans' => false,
+       'pmChannels' => false,
+       'disabledEvents' => [
+           Event::MESSAGE_CREATE, Event::MESSAGE_DELETE, // ...
+       ],
+       'loop' => \React\EventLoop\Factory::create(),
+       'logger' => new \Monolog\Logger('New logger'),
+       'dnsConfig' => '1.1.1.1',
+       'shardId' => 0,
+       'shardCount' => 5,
+   ]);
+
+``token`` is your Discord token. **Required**.
+
+``intents`` can be an array of valid intents *or* an integer representing the intents. Default is all intents minus any privileged intents. At the moment this means all intents minus ``GUILD_MEMBERS`` and ``GUILD_PRESENCES``. To enable these intents you must first enable them in your Discord developer portal.
+
+``loadAllMembers`` is a boolean whether all members should be fetched and stored on bot start. Loading members takes a while to retrieve from Discord and store, so default is false. This requires the ``GUILD_MEMBERS`` intent to be enabled in DiscordPHP. See above for more details.
+
+``storeMessages`` is a boolean whether messages received and sent should be stored. Default is false.
+
+``retrieveBans`` is a boolean whether bans should be retrieved on bot load. Default is false.
+
+``pmChannels`` is a boolean whether PM channels should be stored on bot load. Default is false.
+
+``disabledEvents`` is an array of events that will be disabled. By default all events are enabled.
+
+``loop`` is an instance of a ReactPHP event loop that can be provided to the client rather than creating a new loop. Useful if you want to use other React components. By default, a new loop is created.
+
+``logger`` is an instance of a logger that implements ``LoggerInterface``. By default, a new Monolog logger with log level DEBUG is created to print to stdout.
+
+``dnsConfig`` is an instace of ``Config`` or a string of name server address. By default system setting is used and fall back to 8.8.8.8 when system configuration is not found. Currently only used for VoiceClient.
+
+----
+
+The following options should only be used by large bots that require sharding. If you plan to use sharding, `read up <https://discord.com/developers/docs/topics/gateway#sharding>`_ on how Discord implements it.
+
+``shardId`` is the ID of the bot shard.
+
+``shardCount`` is the number of shards that you are using.
+
+----
+
+Gateway events should be registered inside the ``ready`` event, which is emitted once when the bot first starts and has connected to the gateway.
+
+To register an event we use the ``$discord->on(...)`` function, which registers a handler. A list of events is available `here <https://github.com/discord-php/DiscordPHP/blob/master/src/Discord/WebSockets/Event.php#L30-L75>`_. They are described in more detail in further sections of the documentation. All events take a callback which is called when the event is triggered, and the callback is called with an object representing the content of the event and an instance of the ``Discord`` client.
+
+.. code:: php
+
+   $discord->on('ready', function (Discord $discord) {
+
+       $discord->on(Event::MESSAGE_CREATE, function (Message $message, Discord $discord) {
+           // ... handle message sent
+       });
+
+   });
+
+
+Finally, the event loop needs to be started. Treat this as an infinite loop.
+
+.. code:: php
+
+   $discord->run();
+
+If you want to stop the bot you can run:
+
+.. code:: php
+
+   $discord->close();
+
+If you want to stop the bot without stopping the event loop, the close function takes a boolean:
+
+.. code:: php
+
+   $discord->close(false);

guide/collection.rst

@@ -0,0 +1,258 @@
+==========
+Collection
+==========
+
+
+Collections are exactly what they sound like - collections of items. In DiscordPHP collections are based around the idea of parts, but they can be used for any type of item.
+
+.. container::
+
+   Collections implement interfaces allowing them to be accessed like arrays, such as:
+
+   .. code:: php
+
+      // square bracket index access
+      $collec[123] = 'asdf';
+      echo $collec[123]; // asdf
+
+      // foreach loops
+      foreach ($collec as $item) {
+          // ...
+      }
+
+      // json serialization
+      json_encode($collec);
+
+      // array serialization
+      $collecArray = (array) $collec;
+
+      // string serialization
+      $jsonCollec = (string) $collec; // same as json_encode($collec)
+
+Creating a collection
+=====================
+
++---------+----------------+--------------------------------------------------------------------+
+| name    | type           | description                                                        |
++=========+================+====================================================================+
+| items   | array          | Array of items for the collection. Default is empty collection     |
++---------+----------------+--------------------------------------------------------------------+
+| discrim | string or null | The discriminator used to discriminate between parts. Default ‘id’ |
++---------+----------------+--------------------------------------------------------------------+
+| class   | string or null | The type of class contained in the collection. Default null        |
++---------+----------------+--------------------------------------------------------------------+
+
+.. code:: php
+
+   // Creates an empty collection with discriminator of 'id' and no class type.
+   // Any item can be inserted into this collection.
+   $collec = new Collection();
+
+   // Creates an empty collection with no discriminator and no class type.
+   // Similar to a laravel collection.
+   $collec = new Collection([], null, null);
+
+Getting an item
+===============
+
+Gets an item from the collection, with a key and value.
+
+===== ==== ===================================
+name  type description
+===== ==== ===================================
+key   any  The key to search with
+value any  The value that the key should match
+===== ==== ===================================
+
+.. code:: php
+
+   // Collection with 3 items, discriminator is 'id', no class type
+   $collec = new Collection([
+       [
+           'id' => 1,
+           'text' => 'My ID is 1.'
+       ],
+       [
+           'id' => 2,
+           'text' => 'My ID is 2.'
+       ],
+       [
+           'id' => 3,
+           'text' => 'My ID is 3.'
+       ]
+   ]);
+
+   // [
+   //     'id' => 1,
+   //     'text' => 'My ID is 1.'
+   // ]
+   $item = $collec->get('id', 1);
+
+   // [
+   //     'id' => 1,
+   //     'text' => 'My ID is 1.'
+   // ]
+   $item = $collec->get('text', 'My ID is 1.');
+
+Adding an item
+==============
+
+Adds an item to the collection. Note that if ``class`` is set in the constructor and the class of the item inserted is not the same, it will not insert.
+
+===== ==== ==================
+name  type description
+===== ==== ==================
+$item any  The item to insert
+===== ==== ==================
+
+.. code:: php
+
+   // empty, no discrim, no class
+   $collec = new Collection([], null, null);
+
+   $collec->push(1);
+   $collec->push('asdf');
+   $collec->push(true);
+
+   // ---
+
+   class X
+   {
+       public $y;
+
+       public function __construct($y)
+       {
+           $this->y = $y;
+       }
+   }
+
+   // empty, discrim 'y', class X
+   $collec = new Collection([], 'y', X::class);
+   $collec->push(new X(123));
+   $collec->push(123); // won't insert
+
+   // new X(123)
+   $collec->get('y', 123);
+
+Pulling an item
+===============
+
+Removes an item from the collection and returns it.
+
+======= ==== =========================================
+name    type description
+======= ==== =========================================
+key     any  The key to look for
+default any  Default if key is not found. Default null
+======= ==== =========================================
+
+.. code:: php
+
+   $collec = new Collection([], null, null);
+   $collec->push(1);
+   $collec->push(2);
+   $collec->push(3);
+
+   $collec->pull(1); // returns at 1 index - which is actually 2
+   $collec->pull(100); // returns null
+   $collec->pull(100, 123); // returns 123
+
+Filling the collection
+======================
+
+Fills the collection with an array of items.
+
+.. code:: php
+
+   $collec = new Collection([], null, null);
+   $collec->fill([
+       1, 2, 3, 4,
+   ]);
+
+Number of items
+===============
+
+Returns the number of items in the collection.
+
+.. code:: php
+
+   $collec = new Collection([
+       1, 2, 3
+   ], null, null);
+
+   echo $collec->count(); // 3
+
+Getting the first item
+======================
+
+Gets the first item of the collection.
+
+.. code:: php
+
+   $collec = new Collection([
+       1, 2, 3
+   ], null, null);
+
+   echo $collec->first(); // 1
+
+Filtering a collection
+======================
+
+Filters the collection with a given callback function. The callback function is called for every item and is called with the item. If the callback returns true, the item is added to the new collection. Returns a new collection.
+
+======== ======== =================================
+name     type     description
+======== ======== =================================
+callback callable The callback called on every item
+======== ======== =================================
+
+.. code:: php
+
+   $collec = new Collection([
+       1, 2, 3, 100, 101, 102
+   ], null, null);
+
+   // [ 101, 102 ]
+   $newCollec = $collec->filter(function ($item) {
+       return $item > 100;
+   });
+
+Clearing a collection
+=====================
+
+Clears the collection.
+
+.. code:: php
+
+   $collec->clear(); // $collec = []
+
+Mapping a collection
+====================
+
+A given callback function is called on each item in the collection, and the result is inserted into a new collection.
+
+======== ======== =================================
+name     type     description
+======== ======== =================================
+callback callable The callback called on every item
+======== ======== =================================
+
+.. code:: php
+
+   $collec = new Collection([
+       1, 2, 3, 100, 101, 102
+   ], null, null);
+
+   // [ 100, 200, 300, 10000, 10100, 10200 ]
+   $newCollec = $collec->map(function ($item) {
+       return $item * 100;
+   });
+
+Converting to array
+===================
+
+Converts a collection to an array.
+
+.. code:: php
+
+   $arr = $collec->toArray();