Redis HSETNX in PHP (Detailed Guide w/ Code Examples)

Use Case(s)

The HSETNX command in Redis is used to set a field in a hash stored at key only if the field does not exist. In PHP, it's often used when you want to ensure uniqueness of a certain field in a hash. This can be useful in scenarios where multiple processes are trying to write to the same key simultaneously and you want to avoid overwrites.

Code Examples

Below is an example of how to use HSETNX with phpredis:

$redis = new Redis(); $redis->connect('', 6379); $key = 'user:1'; $field = 'email'; $value = ''; if ($redis->hSetNx($key, $field, $value)) { echo 'Field was set'; } else { echo 'Failed to set field'; }

In this example, we first establish a connection to the Redis server running on localhost ( and port 6379. Then, we try to set a field named 'email' in a hash at key 'user:1' with the value ''. The hSetNx function will return true if the field was set successfully (i.e., the field did not previously exist). If the field already exists, then nothing is done and the function returns false.

Best Practices

  1. Always handle the return of hSetNx function properly as it can tell you whether the operation was successful or not.
  2. Be aware that if multiple concurrent requests are made, only one will succeed. Consider your application's needs and whether this "first one wins" scenario is appropriate.
  3. Always validate the data before inserting into Redis to ensure data integrity.

Common Mistakes

  1. Not checking the return value of hSetNx: It's important to handle the case where hSetNx did not set the field because it already existed, as ignoring this could lead to unexpected behavior in your application.
  2. Assuming hSetNx behaves like hSet: Unlike hSet, hSetNx will not overwrite existing fields. If you want to overwrite fields regardless of their existence, use hSet.


Q: Can I use hSetNx to set multiple fields at once? A: No, hSetNx only sets a single field. If you want to set multiple fields, you can use hMset but bear in mind hMset does not provide the "only if not exists" functionality of hSetNx.

Was this content helpful?

Start building today

Dragonfly is fully compatible with the Redis ecosystem and requires no code changes to implement.