Merge pull request #928 from SQKo/patch-120 @builddocs

BC unavailable Event::GUILD_CREATE, component message non empty, mutable guild feature, deletable message, automod audit log

docs/src/pages/api/03_events/01_application_commands.md

@@ -4,12 +4,10 @@ title: "Application Commands"
 
 ### Application Command Permissions Update
 
-Called with an `Overwrite` object when an application command's permissions are updated.
+Called with an `CommandPermissions` object when an application command's permissions are updated.
 
 ```php
-// use Discord\Parts\Interactions\Command\Overwrite;
-
-$discord->on(Event::APPLICATION_COMMAND_PERMISSIONS_UPDATE, function (Overwrite $overwrite, Discord $discord, Overwrite $oldOverwrite) {
+$discord->on(Event::APPLICATION_COMMAND_PERMISSIONS_UPDATE, function (CommandPermissions $commandPermission, Discord $discord, ?CommandPermissions $oldCommandPermission) {
     // ...
 });
 ```

docs/src/pages/api/03_events/02_auto_moderations.md

@@ -21,7 +21,7 @@ Requires the `Intents::AUTO_MODERATION_CONFIGURATION` intent.
 Called with a `Rule` object when an auto moderation rule is updated.
 
 ```php
-$discord->on(Event::AUTO_MODERATION_RULE_UPDATE, function (Rule $rule, Discord $discord, Rule $oldRule) {
+$discord->on(Event::AUTO_MODERATION_RULE_UPDATE, function (Rule $rule, Discord $discord, ?Rule $oldRule) {
     // ...
 });
 ```

docs/src/pages/api/03_events/03_channels.md

@@ -79,13 +79,19 @@ $discord->on(Event::THREAD_UPDATE, function (Thread $thread, Discord $discord, ?
 Called with an old `Thread` object when a thread relevant to the Bot is deleted.
 
 ```php
-$discord->on(Event::THREAD_DELETE, function ($thread, Discord $discord) {
+$discord->on(Event::THREAD_DELETE, function (object $thread, Discord $discord) {
+    if ($thread instanceof Thread) {
+        // $thread was cached
+    }
+    // $thread was not in cache:
+    else {
     // {
     //     "type": 0,
     //     "id": "",
     //     "guild_id": "",
     //     "parent_id": ""
     // }
+    }
 });
 ```
 

docs/src/pages/api/03_events/04_guilds.md

@@ -8,13 +8,22 @@ Requires the `Intents::GUILDS` intent.
 
 Called with a `Guild` object in one of the following situations:
 
-1. When the Bot is first starting and the guilds are becoming available.
+1. When the Bot is first starting and the guilds are becoming available. (unless the listener is put inside after 'ready' event)
 2. When a guild was unavailable and is now available due to an outage.
 3. When the Bot joins a new guild.
 
 ```php
-$discord->on(Event::GUILD_CREATE, function (Guild $guild, Discord $discord) {
-    // ...
+$discord->on(Event::GUILD_CREATE, function (object $guild, Discord $discord) {
+    if (! ($guild instanceof Guild)) {
+        // the guild is unavailable due to an outage, $guild is a stdClass
+        // {
+        //     "id": "",
+        //     "unavailable": true,
+        // }
+        return;
+    }
+
+    // the Bot has joined the guild
 });
 ```
 
@@ -36,7 +45,7 @@ Called with a `Guild` object in one of the following situations:
 2. The guild is unavailable due to an outage.
 
 ```php
-$discord->on(Event::GUILD_DELETE, function ($guild, Discord $discord, bool $unavailable) {
+$discord->on(Event::GUILD_DELETE, function (object $guild, Discord $discord, bool $unavailable) {
     // ...
     if ($unavailable) {
         // the guild is unavailabe due to an outage, $guild is a stdClass
@@ -128,7 +137,7 @@ $discord->on(Event::GUILD_MEMBER_REMOVE, function (Member $member, Discord $disc
 Called with two `Member` objects when a member is updated in a guild. Note that the old member _may_ be `null` if `loadAllMembers` is disabled.
 
 ```php
-$discord->on(Event::GUILD_MEMBER_UPDATE, function (Member $member, Discord $discord, Member $oldMember) {
+$discord->on(Event::GUILD_MEMBER_UPDATE, function (Member $member, Discord $discord, ?Member $oldMember) {
     // ...
 });
 ```
@@ -162,11 +171,11 @@ $discord->on(Event::GUILD_ROLE_UPDATE, function (Role $role, Discord $discord, ?
 Called with a `Role` object when a role is deleted in a guild. `$role` may return `Role` object if it was cached.
 
 ```php
-$discord->on(Event::GUILD_ROLE_DELETE, function ($role, Discord $discord) {
+$discord->on(Event::GUILD_ROLE_DELETE, function (object $role, Discord $discord) {
     if ($role instanceof Role) {
-        // Role is present in cache
+        // $role was cached
     }
-    // If the role is not present in the cache:
+    // $role was not in cache:
     else {
         // {
         //     "guild_id": "" // role guild ID
@@ -239,8 +248,16 @@ Requires the `Intents::GUILD_INTEGRATIONS` intent.
 Called with a cached `Guild` object when a guild integration is updated.
 
 ```php
-$discord->on(Event::GUILD_INTEGRATIONS_UPDATE, function (?Guild $guild, Discord $discord) {
-    // ...
+$discord->on(Event::GUILD_INTEGRATIONS_UPDATE, function (object $guild, Discord $discord) {
+    if ($guild instanceof Guild) {
+        // $guild was cached
+    }
+    // $guild was not in cache:
+    else {
+        // {
+        //     "guild_id": "",
+        // }
+    }
 });
 ```
 
@@ -269,12 +286,17 @@ $discord->on(Event::INTEGRATION_UPDATE, function (Integration $integration, Disc
 Called with an old `Integration` object when a integration is deleted from a guild.
 
 ```php
-$discord->on(Event::INTEGRATION_DELETE, function ($integration, Discord $discord) {
-    // if $integration is not cached,
-    // {
-    //     "id": "",
-    //     "guild_id": "",
-    //     "application_id": ""
-    // }
+$discord->on(Event::INTEGRATION_DELETE, function (object $integration, Discord $discord) {
+    if ($integration instanceof Integration) {
+        // $integration was cached
+    }
+    // $integration was not in cache:
+    else {
+        // {
+        //     "id": "",
+        //     "guild_id": "",
+        //     "application_id": ""
+        // }
+    }
 });
 ```

docs/src/pages/api/03_events/05_invites.md

@@ -19,11 +19,11 @@ $discord->on(Event::INVITE_CREATE, function (Invite $invite, Discord $discord) {
 Called with an object when an invite is created.
 
 ```php
-$discord->on(Event::INVITE_DELETE, function ($invite, Discord $discord) {
+$discord->on(Event::INVITE_DELETE, function (object $invite, Discord $discord) {
     if ($invite instanceof Invite) {
-        // Invite is present in cache
+        // $invite was cached
     }
-    // If the invite is not present in the cache:
+    // If $invite was not in cache:
     else {
         // {
         //     "channel_id": "",

docs/src/pages/api/03_events/07_messages.md

@@ -35,11 +35,11 @@ The `Message` object may be the raw payload if `storeMessages` is not enabled _o
 Discord does not provide a way to get deleted messages.
 
 ```php
-$discord->on(Event::MESSAGE_DELETE, function ($message, Discord $discord) {
+$discord->on(Event::MESSAGE_DELETE, function (object $message, Discord $discord) {
     if ($message instanceof Message) {
-        // Message is present in cache
+        // $message was cached
     }
-    // If the message is not present in the cache:
+    // $message was not in cache:
     else {
         // {
         //     "id": "", // deleted message ID,
@@ -60,9 +60,9 @@ Discord does not provide a way to get deleted messages.
 $discord->on(Event::MESSAGE_DELETE_BULK, function (Collection $messages, Discord $discord) {
     foreach ($messages as $message) {
         if ($message instanceof Message) {
-            // Message is present in cache
+            // $message was cached
         }
-        // If the message is not present in the cache:
+        // $message was not in cache:
         else {
             // {
             //     "id": "", // deleted message ID,

docs/src/pages/api/03_events/11_webhooks.md

@@ -7,11 +7,11 @@ title: "Webhooks"
 Called with a `Guild` and `Channel` object when a guild channel's webhooks are is created, updated, or deleted.
 
 ```php
-$discord->on(Event::WEBHOOKS_UPDATE, function ($guild, Discord $discord, $channel) {
+$discord->on(Event::WEBHOOKS_UPDATE, function (object $guild, Discord $discord, object $channel) {
     if ($guild instanceof Guild && $channel instanceof Channel) {
-        // Guild and Channel is present in cache
+        // $guild and $channel was cached
     }
-    // If not present in the cache:
+    // $guild and/or $channel was not in cache:
     else {
         // {
         //     "guild_id": "" // webhook guild ID

src/Discord/Builders/MessageBuilder.php

@@ -662,6 +662,7 @@ public function jsonSerialize(): array
 
         if (isset($this->components)) {
             $body['components'] = $this->components;
+            $empty = false;
         }
 
         if ($this->sticker_ids) {

src/Discord/Discord.php

@@ -473,11 +473,9 @@ protected function handleReady(object $data)
             /** @var ExtendedPromiseInterface */
             $promise = coroutine([$event, 'handle'], $guild);
 
-            $promise->done(null, function ($d) use (&$unavailable) {
-                list($status, $data) = $d;
-
-                if ($status == 'unavailable') {
-                    $unavailable[$data] = $data;
+            $promise->done(function ($d) use (&$unavailable) {
+                if (! empty($d->unavailable)) {
+                    $unavailable[$d->id] = $d->unavailable;
                 }
             });
         }
@@ -496,8 +494,10 @@ protected function handleReady(object $data)
         $guildLoad = new Deferred();
 
         $onGuildCreate = function ($guild) use (&$unavailable, $guildLoad) {
-            $this->logger->debug('guild available', ['guild' => $guild->id, 'unavailable' => count($unavailable)]);
-            unset($unavailable[$guild->id]);
+            if (empty($guild->unavailable)) {
+                $this->logger->debug('guild available', ['guild' => $guild->id, 'unavailable' => count($unavailable)]);
+                unset($unavailable[$guild->id]);
+            }
             if (count($unavailable) < 1) {
                 $guildLoad->resolve();
             }
@@ -508,9 +508,9 @@ protected function handleReady(object $data)
             if ($guild->unavailable) {
                 $this->logger->debug('guild unavailable', ['guild' => $guild->id, 'unavailable' => count($unavailable)]);
                 unset($unavailable[$guild->id]);
-                if (count($unavailable) < 1) {
-                    $guildLoad->resolve();
-                }
+            }
+            if (count($unavailable) < 1) {
+                $guildLoad->resolve();
             }
         };
         $this->on(Event::GUILD_DELETE, $onGuildDelete);

src/Discord/Parts/Channel/Channel.php

@@ -261,6 +261,8 @@ protected function getGuildAttribute(): ?Guild
      * Gets the last pinned message timestamp.
      *
      * @return Carbon|null
+     *
+     * @throws \Exception
      */
     protected function getLastPinTimestampAttribute(): ?Carbon
     {

src/Discord/Parts/Channel/Invite.php

@@ -178,8 +178,6 @@ protected function getChannelIdAttribute(): ?string
     /**
      * Returns the inviter attribute.
      *
-     * @throws \Exception
-     *
      * @return User|null The User that invited you.
      */
     protected function getInviterAttribute(): ?User
@@ -230,9 +228,9 @@ protected function getTargetApplicationAttribute(): ?Application
     /**
      * Returns the expires at attribute.
      *
-     * @throws \Exception
-     *
      * @return Carbon|null The time that the invite was created.
+     *
+     * @throws \Exception
      */
     protected function getExpiresAtAttribute(): ?Carbon
     {
@@ -267,6 +265,8 @@ protected function getGuildScheduledEventAttribute(): ?ScheduledEvent
      * Returns the created at attribute.
      *
      * @return Carbon|null The time that the invite was created.
+     *
+     * @throws \Exception
      */
     protected function getCreatedAtAttribute(): ?Carbon
     {

src/Discord/Parts/Channel/Message.php

@@ -603,6 +603,8 @@ protected function getReferencedMessageAttribute(): ?Message
      * Returns the timestamp attribute.
      *
      * @return Carbon|null The time that the message was sent.
+     *
+     * @throws \Exception
      */
     protected function getTimestampAttribute(): ?Carbon
     {
@@ -617,6 +619,8 @@ protected function getTimestampAttribute(): ?Carbon
      * Returns the edited_timestamp attribute.
      *
      * @return Carbon|null The time that the message was edited.
+     *
+     * @throws \Exception
      */
     protected function getEditedTimestampAttribute(): ?Carbon
     {
@@ -800,7 +804,7 @@ public function delayedDelete(int $delay, &$timer = null): ExtendedPromiseInterf
         $deferred = new Deferred();
 
         $timer = $this->discord->getLoop()->addTimer($delay / 1000, function () use ($deferred) {
-            $this->delete([$deferred, 'resolve'], [$deferred, 'reject']);
+            $this->delete()->done([$deferred, 'resolve'], [$deferred, 'reject']);
         });
 
         return $deferred->promise();
@@ -901,9 +905,15 @@ private function _edit(MessageBuilder $message): ExtendedPromiseInterface
      * @link https://discord.com/developers/docs/resources/channel#delete-message
      *
      * @return ExtendedPromiseInterface
+     *
+     * @throws \RuntimeException This type of message cannot be deleted.
      */
     public function delete(): ExtendedPromiseInterface
     {
+        if (! $this->isDeletable()) {
+            return reject(new \RuntimeException("Cannot delete this type of message: {$this->type}", 50021));
+        }
+
         return $this->http->delete(Endpoint::bind(Endpoint::CHANNEL_MESSAGE, $this->channel_id, $this->id));
     }
 
@@ -973,6 +983,22 @@ public function addEmbed(Embed $embed): ExtendedPromiseInterface
             ->addEmbed($embed));
     }
 
+    public function isDeletable(): bool
+    {
+        return ! in_array($this->type, [
+            self::TYPE_RECIPIENT_ADD,
+            self::TYPE_RECIPIENT_REMOVE,
+            self::TYPE_CALL,
+            self::TYPE_CHANNEL_NAME_CHANGE,
+            self::TYPE_CHANNEL_ICON_CHANGE,
+            self::TYPE_GUILD_DISCOVERY_DISQUALIFIED,
+            self::TYPE_GUILD_DISCOVERY_REQUALIFIED,
+            self::TYPE_GUILD_DISCOVERY_GRACE_PERIOD_INITIAL_WARNING,
+            self::TYPE_GUILD_DISCOVERY_GRACE_PERIOD_FINAL_WARNING,
+            self::TYPE_THREAD_STARTER_MESSAGE,
+        ]);
+    }
+
     /**
      * @inheritDoc
      *

src/Discord/Parts/Channel/Overwrite.php

@@ -50,7 +50,6 @@ class Overwrite extends Part
      * Sets the allow attribute of the role.
      *
      * @param  ChannelPermission|int $allow
-     * @throws \Exception
      */
     protected function setAllowAttribute($allow): void
     {
@@ -65,7 +64,6 @@ protected function setAllowAttribute($allow): void
      * Sets the deny attribute of the role.
      *
      * @param  ChannelPermission|int $deny
-     * @throws \Exception
      */
     protected function setDenyAttribute($deny): void
     {

src/Discord/Parts/Embed/Embed.php

@@ -70,6 +70,8 @@ class Embed extends Part
      * Gets the timestamp attribute.
      *
      * @return Carbon|null The timestamp attribute.
+     *
+     * @throws \Exception
      */
     protected function getTimestampAttribute(): ?Carbon
     {

src/Discord/Parts/Guild/AuditLog/Entry.php

@@ -86,6 +86,8 @@ class Entry extends Part
     public const AUTO_MODERATION_RULE_UPDATE = 141;
     public const AUTO_MODERATION_RULE_DELETE = 142;
     public const AUTO_MODERATION_BLOCK_MESSAGE = 143;
+    public const AUTO_MODERATION_FLAG_TO_CHANNEL = 144;
+    public const AUTO_MODERATION_USER_COMMUNICATION_DISABLED = 145;
 
     // AUDIT LOG ENTRY TYPES