From db07895d3bba578b79482933948734fdba9cdba3 Mon Sep 17 00:00:00 2001
From: Vincent Garnier <forxer@gmail.com>
Date: Thu, 16 Mar 2023 15:15:33 +0100
Subject: [PATCH] Removed `gravatar()` and `gravatar_profile()` helpers
 functions

---
 CHANGELOG.md    |  8 ++++++++
 README.md       | 41 ++++++++++++++++++++++++++++++++++++++++-
 UPGRADE.md      | 10 ++++++++++
 composer.json   |  5 +----
 src/helpers.php | 30 ------------------------------
 5 files changed, 59 insertions(+), 35 deletions(-)
 delete mode 100644 src/helpers.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f09e5db..3d9167e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,13 @@
 CHANGELOG
 =========
 
+4.0.0 (2023-03-16)
+------------------
+
+- Removed `gravatar()` and `gravatar_profile()` helpers functions
+- Added documentation to implement own helpers
+
+
 3.0.1 (2023-03-16)
 ------------------
 
@@ -8,6 +15,7 @@ CHANGELOG
 - Improved README.md file
 - Uppercased "README" and "CHANGELOG" files
 
+
 3.0.0 (2023-03-16)
 ------------------
 
diff --git a/README.md b/README.md
index 6b4b62e..49021a9 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@ Usage
 
 There are many ways to use this library:
 
-- Use helpers fonctions `gravatar()` and `gravatar_profile()`
+- Use helpers fonctions
 - Use the Gravatar base class with its `Gravatar::image()` and `Gravatar::profile()` methods
 - Instantiate the dedicated classes `Gravatar\Image()` and `Gravatar\Profile()`
 
@@ -93,6 +93,45 @@ Whatever method you use, you could use the `url()` method to retrieve it. Or dis
 
 The easiest way to use this library is to use the helper functions.
 
+Since version 4, in order to avoid conflicts with other packages, we no longer define the `gravatar()` and `gravatar_profile()` helpers. It's up to you to do this in your app with names that work for you and don't conflict with others. Here's how to do it; it's simple.
+
+In a file dedicated to the helper functions, define the version 3 functions using the names that suit you.
+
+```php
+<?php
+
+use Gravatar\Image;
+use Gravatar\Profile;
+
+if (! function_exists('gravatar')) {
+    /**
+     * Return a new Gravatar Image instance.
+     *
+     * @param string|null $email
+     * @return Image
+     */
+    function gravatar(?string $email = null): Image
+    {
+        return new Image($email);
+    }
+}
+
+if (! function_exists('gravatar_profile')) {
+    /**
+     * Return a new Gravatar Profile instance.
+     *
+     * @param string|null $email
+     * @return Profile
+     */
+    function gravatar_profile(?string $email = null): Profile
+    {
+        return new Profile($email);
+    }
+}
+```
+
+This way you can use them like this:
+
 ```php
 <?php
 require 'vendor/autoload.php';
diff --git a/UPGRADE.md b/UPGRADE.md
index caa8241..deb0010 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -1,6 +1,16 @@
 UPGRADE
 =======
 
+From 3.x to 4.x
+---------------
+
+In version 3 I introduced 2 helpers `gravatar()` and `gravatar_profile()` but it was a bad idea.
+
+The `gravatar()` and `gravatar_profile()` helpers have been removed from the package because they could conflict with other global functions of the same name.
+
+I prefer to indicate how to define your own helpers rather than embedding them "hard" in the package.
+
+
 From 2.x to 3.x
 ---------------
 
diff --git a/composer.json b/composer.json
index b593896..5ad0563 100644
--- a/composer.json
+++ b/composer.json
@@ -17,10 +17,7 @@
 	"autoload" : {
 		"psr-4" : {
 			"Gravatar\\" : "src"
-		},
-        "files": [
-            "src/helpers.php"
-        ]
+		}
 	},
 	"minimum-stability" : "dev",
 	"support" : {
diff --git a/src/helpers.php b/src/helpers.php
deleted file mode 100644
index 6ca7d12..0000000
--- a/src/helpers.php
+++ /dev/null
@@ -1,30 +0,0 @@
-<?php
-
-use Gravatar\Image;
-use Gravatar\Profile;
-
-if (! function_exists('gravatar')) {
-    /**
-     * Return a new Gravatar Image instance.
-     *
-     * @param string|null $email
-     * @return Image
-     */
-    function gravatar(?string $email = null): Image
-    {
-        return new Image($email);
-    }
-}
-
-if (! function_exists('gravatar_profile')) {
-    /**
-     * Return a new Gravatar Profile instance.
-     *
-     * @param string|null $email
-     * @return Profile
-     */
-    function gravatar_profile(?string $email = null): Profile
-    {
-        return new Profile($email);
-    }
-}